CLI reference¶

Once installed, flower is a single executable with 4 subcommands and 23 flags. This page lists them all: the type, default value, and exact semantics of every flag, plus how to talk to it mid-run, what it asks on first launch, what the exit codes are, and which files it puts in your directory. After reading this page you shouldn't need to open the source.

Source: flower/cli.py.

Total flags 23 = 5 global + 11 specific to go + 6 specific to once + -h/--help. run and setup have no flags of their own.

Invocation forms¶

All of flower's argv first passes through _with_default_cmd() to fill in the default subcommand, then goes to argparse (cli.py:1437-1439). That's why flower "帮我做一个 X" works — it gets rewritten into flower go "帮我做一个 X".

The rules for filling in the default subcommand (cli.py:940-976):

1. The set of global flags is derived from the main parser itself, not a hardcoded list. Those with nargs == 0 count as pure flags; the rest count as value-taking flags.
2. Scan left to right, skipping global flags. Value-taking ones skip their value too, and the = form such as --workspace=/tmp is recognized as well.
3. Stop at the first token that isn't a global flag. If it is one of go, run, once, hand it to argparse as-is; otherwise insert a go before it, so it becomes the body of go's request.
4. If the scan finishes without hitting a positional (empty argv, or only global flags) → append go at the end, and enter interactive input.
5. Exception: when argv contains -h or --help, return it as-is and let argparse print help.

The constant used for the decision is _CMDS = ("go", "run", "once") (cli.py:937) — setup is not in it; see setup for the consequences.

What the rewriting actually produces¶

The two words run and once cannot be used directly as a request body; this ambiguity is deliberately preserved (cli.py:949-950). To use them as a request, write flower go run.

Six usable forms¶

flower                                    # 1. 裸跑:交互问“要做什么?”或“接着上次?”
flower "帮我做一个 X"                       # 2. 位置参数给诉求
echo "帮我做一个 X" | flower --timeout 0    # 3. 管道喂 stdin
flower once "读一眼这个仓库"                 # 4. 单 agent
flower run flows.py:main                  # 5. 跑自定义流程
flower go setup                           # 6. 显式 go,把 setup 当诉求正文

The module form python -m flower.cli is equivalent to flower (cli.py:1451-1452). The container wrapper docker/flowerbox takes exactly the same arguments as flower.

Feeding stdin through a pipe¶

When sys.stdin.isatty() is false, ask_for_prompt() does not print the prompt header and directly does input("> ") to read one line (cli.py:993-1001). So echo "..." | flower works.

But a warning line is printed afterwards, and the stdin thread immediately reads EOF and exits:

! 标准输入不是终端,没人能回答提问。想让它自己判断就加 --timeout 0

A piped run should be paired with --timeout 0: questions no longer pretend to wait 30 minutes, they fail immediately, and the agent decides for itself and writes the assumptions into the "未知与假设" section of the brief.

Subcommands¶

go¶

Help text: 一键跑:问清需求 → 派人干活(不写子命令时的默认) (cli.py:1275-1307).

Positional argument ask, nargs="?" — omit it and you get interactive input. This is the most common entry point; flower "做 X" goes through it.

What it does (cli.py:1190-1221):

1. ensure_credentials() — check credentials, and actually fire one API probe; see First-run configuration flow.
2. Wake detection: read-only glance at whether this directory has been used, without writing a single byte.
3. If no ask was given, print a prompt and ask; typing /new is equivalent to --new, and then it asks again for the request.
4. If this is a continuity, print a one-line wake banner.
5. Build a three-step workflow: 确认需求 → 设定目标 → 干活, with a 干活·判定#N following each work round. --clarify-only keeps only the first step.
6. Start running.

The wake banner looks like this (the home directory in the path is replaced by ~):

<- 在 ~/proj 接上上次  需求已确认 · 目标 7 条 · 干活上下文 71.4K · 第 3 次唤醒

需求已确认 is always present; 目标 N 条 only appears when there is a verdict checklist; 干活上下文 X requires that the last round's context for that session can be looked up in sessions.db — if not found, it isn't shown.

The 11 flags of go¶

Edge cases in values — none of them error, none of them warn:

• --rounds 0 and --rounds 1 are equivalent — internally it's retries = max(0, rounds - 1), both run 1 round.
• Any negative value for --asks means unlimited, not just -1.
• Any negative value for --timeout equals 0, i.e. fully automatic.
• --window 0 is silently ignored (0 is falsy and simply isn't passed down), falling back to the default inferred from the model name. Negative values do get passed down, and are then floored to 10000.
• --clarify-only is a no-op on an already-clarified directory — the 确认需求 step sees a complete 需求.md and skips, and since that's the only step in the workflow, nothing happens (other than wake count +1). To re-clarify you need --new.
• The end of go's --help says "全局开关(-v/-w/-r/-T)见 flower --help" — this line omits -W.

run¶

Help text: 运行一个 workflow (cli.py:1309-1312).

Positional argument target, written as module:attribute. Both forms are supported (cli.py:1010-1031):

flower run mypkg.flows:build     # 按模块名 import
flower run flows.py:build        # 文件路径;会把父目录塞进 sys.path 再按文件名 import

If the attribute obtained is callable, it is called once and the return value is used as the workflow; if it is already a workflow object, it is used directly.

run has no flags of its own, only the 5 global flags. So on this path things like --window and --no-handoff all take their default values (the code falls back with getattr, cli.py:1041-1043). To adjust them, write the parameters into your own workflow.

once¶

Help text: 跑一次单 agent (cli.py:1314-1324). The positional argument prompt is required.

It constructs an AgentSpec(name="ad-hoc", …) and runs it directly, without going through _drive. So on once there is no:

• Ctrl-C interrupt-and-speak (pressing it is just a plain KeyboardInterrupt)
• stdin answering thread, or the input prompt pinned to the bottom
• oracle Q&A
• SIGHUP / SIGTERM rescue accounting
• closing line 总花费 … · 清单 …
• automatic reconfiguration guidance after credential failure

In the run manifest, the name of this step is fixed as ad-hoc.

setup¶

Help text: 配置凭证(API key / 网关 / 模型),写到 ~/.config/flower/.env (cli.py:1326-1328). It has no flags.

What it does: read .env → determine whether it's been configured → launch the interactive configuration flow, with reason being 重新配置。 or 还没配过凭证。. For the screen contents see First-run configuration flow.

Global flags¶

The 5 global flags are attached to the main parser and to every subcommand at the same time (cli.py:1250-1266). The copies on subcommands use argparse.SUPPRESS, so when not given they don't write an attribute — which means they can be written before or after the subcommand, without overriding each other. The side effect is that they don't appear in a subcommand's --help — to see them run flower --help.

The fact that -r/--run-dir is relative to CWD will bite you: flower -w /other/proj "做 X" creates runs/ in the directory where you typed the command, while .flower/ is created under /other/proj/ — two pieces of state split apart. To keep them together, pass -r /other/proj/runs explicitly.

The help for -v says "显示思考与工具结果", but the main thread's thinking is shown by default. What -v actually additionally enables is:

• subagent body text (not shown by default, only its tool calls are)
• normal tool results (by default only failing ones are shown)
• prompt events
• printing the currently effective credential configuration before startup, with tokens masked to the first 4 characters

That last one uses a bare print(), bypassing output sanitization, without wrapping, and unprotected by the terminal write lock; when running several flower processes in parallel these lines may get torn apart.

How to talk to it mid-run¶

Once the run has started, the terminal is continuously reading your input. You don't need to wait for it to ask, and you don't need to press anything to enter input mode — the last line is always the one you can type on.

The input prompt pinned to the bottom¶

There is a daemon thread flower-stdin reading stdin the whole time (cli.py:764-934), polling with select every 0.2 seconds rather than doing a blocking read (so a stop signal can wake it; on streams that don't support select, such as on Windows, it degrades to a blocking read).

It reads all the time, not only when there's a question. The reason: if it only read while a question is pending, whatever you typed during those hours of work would sit in the terminal buffer and be swallowed as the answer to the next question — the question would be answered before you'd even seen it.

On the display side, _say() is the only output path; before each output it erases the prompt and redraws it afterwards (cli.py:309-315), so the prompt never gets pushed up the screen by event output. On redraw, even the few characters you typed but haven't hit Enter on are drawn back — they're kept in _PROMPT["buf"] (cli.py:183-192). Without this the content wouldn't actually be lost (it's still in the terminal's line buffer, and Enter still sends it), but you couldn't see it, so you'd be unsure and retype it.

The prompt has two wordings, switching on whether there's a pending question:

Character-by-character input mode and keybindings¶

To draw "the half-typed characters" back, flower has to take over input itself. When stdin is a terminal and termios can be imported, the terminal is set to cbreak before the flower-stdin thread is started (cli.py:793-807) — cbreak rather than raw, so that Ctrl+C still produces SIGINT and the whole Ctrl-C mechanism still exists. It must be set before the thread starts: doing it inside the thread is a genuine race, and characters typed in the instant before the thread gets CPU would be swallowed by line mode, showing up as "input lost" (reproduced reliably once in three tries in testing, cli.py:928-934).

If it can't be set, it falls back to the original whole-line readline() (non-terminal, termios unavailable, tcgetattr failure). Both paths work; line mode just doesn't have the keybindings below (cli.py:883-899).

The editing logic lives in LineEditor (cli.py:320-414) — a pure state machine that never touches the terminal:

Enter hands the buffer over and clears it, while moving down a line on screen — what you said stays above (cli.py:811-827).

Where what you typed goes¶

When it goes to the inbox, a receipt line is printed:

+ 收到 (它下次查收件箱时会看到;已追加进确认书)

When there is no brief to spill to, the second half becomes 没有确认书可落盘 —— 它可能活不过下一个步骤. The inbox does not interrupt the worker currently working; it's picked up only the next time the worker checks the inbox on its own. The same sentence is also appended to notes/需求.md; without spilling it wouldn't survive a step boundary — the next step is a new session that only reads frozen artifacts.

Starting with ? = oracle Q&A¶

A line starting with ? is not sent to the running agent, but handed to the oracle:

? 现在到哪一步了

It starts a separate Runtime with run_dir at <run_dir>/aside/, so its cost and session lineage don't get mixed into the main manifest.json. The role is read-only, its tools are only Read, Glob, Grep, at most 12 turns, with a cost cap of $0.5. The context it sees is the most recent 60 events (thinking and prompt events don't enter this window), each truncated to 200 characters, plus a description of the workbench paths.

It runs concurrently; the ongoing run doesn't wait a single second. The answer looks like this:

# 旁路
  <回答正文>
  ($0.0123,没有打扰正在跑的运行)

On failure it prints a red line # 旁路问答失败:<类型>: <消息>, which does not affect the main workflow. On exit it waits at most 120 seconds for the oracle to finish, printing (等 N 条旁路问答收尾…) before waiting.

What it says never enters that run's context — asking doesn't affect the run, and the answer is discarded once given.

if raw.startswith("?") or raw.startswith("?"):

What's on the screen¶

The icons are all ASCII, not emoji (cli.py:51-69). The reason is written in a code comment: emoji together with box-drawing, geometric, and arrow characters trigger terminal glyph fallback, which once caused two terminal crashes.

  ? 这个工具要做成 CLI 还是库?
     1) CLI
     2) 库
     (还能问 5 次)
<- 在 ~/proj 接上上次  需求已确认 · 目标 7 条 · 第 3 次唤醒

The five states of a question appear on screen as:

When --asks is unlimited (the default), the trailing "还能问 N 次" line is not shown.

When handoff finishes writing the handoff document, it's a whole block:

# 上下文 950.0K/1000K —— 写交接准备换代
  - 现在在做    …
  - 已定的事    …
  - 走不通的    …
  - 下一步      …
<- 交接写在 ~/proj/.flower/notes/交接-干活.md
<- 新会话接手,上下文从 950.0K 重新开始

When the handoff document degrades, an extra red line is inserted: 交接没写成,用了降级版本 —— 接手的人会自己去现场看.

The output also does two things you don't see: every output line passes through sanitization that only lets through flower's own SGR color codes, while screen-clearing and cursor-moving sequences emitted by the model or tools are swallowed whole; and the width is taken as max(40, min(terminal columns, 110)), so on a wide terminal it doesn't fill the whole line — that's intentional.

The prompt at launch¶

Running bare flower (without a request) asks first. Two wordings:

要做什么? 一句话就够,回车开始(Ctrl-C 退出)
> 

接着上次? 直接回车 = 接着做;也可以说点新的;/new = 重开一件事(Ctrl-C 退出)
> 

The second only appears when this directory has already been run in and 需求.md has all four sections.

This prompt reads via input(), without going through shell parsing. Chinese quotation marks, spaces, and exclamation marks can all be typed directly — that's the entire reason it exists. zsh, on hitting a Chinese closing quotation mark, drops into a dquote> continuation line, which looks like a hang, when in fact it never launched at all.

• Empty input + first time → exit, printing 诉求是空的。直接 `flower` 然后按提示输入,或者 flower "帮我做一个 X"。
• Empty input + wake → valid, meaning "keep going"
• Typing /new → equivalent to --new; archives the previous segment and then asks again for the request
• Ctrl-C / Ctrl-D → exit, printing 已取消

Timeout¶

--timeout is a float in seconds, defaulting to 1800.0. Three kinds of values:

--timeout 0 and --timeout -1 are exactly equivalent. Piped runs, CI runs, and unattended runs all use this.

When a question gets no answer, the tool result fed back to the model is fixed copy, of four kinds:

Ctrl-C¶

Ctrl-C means completely different things in two places.

Pressed at the launch prompt > — exits the program immediately, printing 已取消.

Pressed mid-run — interrupts the current round and gives you one chance to speak:

! 已打断这一轮。正在跑的 subagent 会丢掉半成品。
  要说什么?(直接回车 = 什么都不说,接着跑;再按一次 Ctrl+C = 退出)
> 

Just hitting Enter here means interrupt without saying anything, and keep going. If there were pending questions at the time, an extra line is printed: (有 N 个提问还等着,打断不影响它们).

Pressing Ctrl+C a second time really exits, and it's an uncaught KeyboardInterrupt — you'll get a Python traceback on screen, not a clean exit.

The interrupt is cooperative: it breaks cleanly at a message boundary, without hard-cancelling tasks. It does not count as a failed attempt and doesn't consume a retry. On resume a note is attached telling the model that "in-flight tool calls returning interrupted is a normal side effect of the interrupt, not an environment failure".

This custom Ctrl-C is installed only when sys.stdin.isatty() (cli.py:1097). When running in a pipe, Python's default behavior is kept, i.e. it exits on the first press. The once path doesn't go through here, so Ctrl-C on once also exits on the first press.

SIGHUP / SIGTERM¶

The go and run paths install handlers for both SIGHUP and SIGTERM: first write the in-flight step into manifest.json too, marked as killed-by-signal, then restore the default action and really leave.

The cause was that when the terminal crashes the kernel sends SIGHUP, whose default action terminates the process outright — finally doesn't run, the manifest isn't written, and a whole run's accounting is lost. On a non-main OS thread, or on platforms without support, it's silently skipped.

First-run configuration flow¶

All three entry points go, run, once call ensure_credentials() at the start (cli.py:1392-1428), with two gates.

Gate one: are there credentials¶

It searches for credentials in priority order. If neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is found, it launches the interactive configuration; when non-interactive (stdin is not a terminal) it doesn't block, and simply prints this and exits:

缺少凭证:需要 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN。
最省事:跑一次 `flower setup`,把 token 存到 /Users/you/.config/flower/.env(装一次,处处生效)。
或者:在当前目录建 `.env`,或 export 进进程环境。
flower 不读 ~/.claude/settings.json —— 那是可移植性的代价。

Two things in this copy don't match the implementation: the flower setup on the second line currently can't be reached (see setup); and the fourth line is the opposite of the code — flower does treat the env block of ~/.claude/settings.json and settings.local.json as a last-level fallback, borrowing only 9 credential keys from it and taking over no other settings. The place that prints this line is env.py:192 (the function check_credentials() is defined at env.py:184), while the code that actually reads those two files is env.py:56-75 and :109-111; recorded as issue #13. The code is authoritative: it does read them. For the full lookup priority and those 9 keys, see the configuration reference.

What the interactive configuration asks¶

== 配置 flower ========================================
<为什么要配这一行>
凭证会存到 /Users/you/.config/flower/.env(只你可读)。装一次,处处生效。

1. 你的 API key 或网关 token (Anthropic 官方的 sk-ant-… 或第三方网关签发的)
   > 

2. 网关地址 (直接回车 = Anthropic 官方;第三方网关填它的 BASE_URL)
   > 

3. 模型名 (直接回车 = 默认;网关有自己的模型名就填,如 claude-opus-5[1m])
   > 

+ 存好了:/Users/you/.config/flower/.env

• Question 1 is required. Leaving it blank prints the red line 没给 token,取消。 and abandons configuration.
• Questions 2 and 3 may be left blank.
• When stdin is not a terminal the whole flow is skipped outright, without blocking.

The keys it writes¶

The file path is ${XDG_CONFIG_HOME:-~/.config}/flower/.env, and the parent directory is created automatically. The write is a full overwrite, keys with empty values are skipped, chmod 0600 follows, and it's loaded into effect immediately — no need to reopen the shell. The first line is always a comment reminding you not to commit it into version control.

Gate two: do the credentials work¶

Once configuration is complete, it prints - 验一下凭证… and then actually fires one API call.

Probe details: POST {BASE_URL}/v1/messages, max_tokens=16, default timeout 20 seconds, using stdlib urllib, no dependencies pulled in. The model is taken in the order ANTHROPIC_DEFAULT_HAIKU_MODEL → ANTHROPIC_MODEL → claude-3-5-haiku-20241022. If ANTHROPIC_API_KEY is present it uses the x-api-key header, otherwise authorization: Bearer <ANTHROPIC_AUTH_TOKEN>.

max_tokens is deliberately 16 rather than 1: in testing, models with forced chain-of-thought can't even fit their thinking in, and the server struggles for 30 seconds before returning; with 16 it takes only 3.6 seconds.

The probe's conclusion is handled in three categories, and the differences matter:

The criterion for config has been tightened: the word model almost inevitably appears in Anthropic-style error JSON, so using it as "wrong model name" would misjudge a transient 400 as a configuration error and then force a reconfiguration — it has to explicitly say "not found / doesn't exist" to count (env.py:176-182).

The net case is deliberate: a network hiccup shouldn't force you to retype your token, and flower itself has a mechanism for hanging and reconnecting when the network goes down. If you see "探针没打通", ignore it and keep running.

The chance to reconfigure is given at most once. A second failure exits.

The probe is only fired in an interactive terminal. ensure_credentials() returns immediately without making that one API call if any of the following holds (cli.py:1413): the caller passed probe=False, FLOWER_NO_PROBE is set, or stdin is not a terminal (pipe / CI / offline tests). The reason is that in a non-interactive setting you can't fix what the probe finds anyway, so its only effect is "failing early" — and failing early is worse than not probing when the probe misjudges. If the credentials really are bad, the run will blow up on its own, and that path is caught by automatic reconfiguration after a crash.

Automatic reconfiguration after a crash¶

When the workflow fails, flower matches the error message of the failing step against a regex (401, invalid api key, authentication, unauthorized, 无效…key/token/密钥). On a match, and when stdin is a terminal, it prints ! 看起来是凭证不对:<前 120 字> on the spot and launches interactive configuration; once configured it prints:

配好了。再跑一次刚才的命令 —— 同一目录会接着上次。

Then it exits with code 1 regardless. The once path doesn't have this.

Exit codes¶

All exit-code-1 messages:

When it finishes (the go / run paths), the last line printed is:

总花费 $1.2345 · 清单 /abs/path/runs/manifest.json

This amount only counts this process's cost, not the previous run's — even though the manifest file itself accumulates across processes.

What it creates in your project¶

Two trees: <run_dir>/ (default ./runs/, relative to CWD) holds accounting and sessions; <workspace>/.flower/ holds the workbench.

runs/¶

The fields of each record in manifest.json:

step  session_id  ok  cost_usd  num_turns  text  error  started_at  ended_at
attempts  errors[]  resumed  retired[]  context  duration_s  run

run is this process's marker, formatted as YYYYmmdd-HHMMSS-<6 位 hex>. The spill policy is append, don't overwrite: before each write it re-reads the file and deduplicates by run — rows belonging to this process are replaced with the latest, rows from other processes are left as they are.

Step names come in four shapes:

When killed by a signal, the in-flight step is written too, with the error field being killed-by-signal.

Running several flowers in parallel in the same directory: manifest.json is safe (re-read + merge by run), but lineage.json is a full overwrite, and two processes will clobber each other's lineage for steps of the same name. To run in parallel, use different -r.

lineage.json stores the absolute path of the workspace. If it doesn't match, it's treated as absent and silently falls back to a new session without an error — after a directory has been copied elsewhere, the old session_id couldn't be looked up anyway.

.flower/¶

The go path always generates these under notes/:

With --isolate the workbench moves outside the repo: <workspace>.parent/.flower-<workspace 名>/. A worktree is each agent's private copy, while the workbench is a shared layer across agents, and shared things can't be put inside a private fence. In this case the workbench path given to the model is an absolute path.