CLI reference¶

flower installs a single executable with 4 subcommands and 23 flags. This page lists all of them: the type, default value and exact semantics of every flag, plus how to interject mid-run, what it asks you on first launch, what the exit codes are, and which files it drops into your directory. After this page you should never 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¶

Every argv flower sees first passes through _with_default_cmd(), which fills in the default subcommand, and only then goes to argparse (cli.py:1437-1439). That is why flower "build me an X" works — it gets rewritten into flower go "build me an 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 from a hardcoded list. Anything with nargs == 0 counts as a bare flag; everything else takes a value.
2. Scan left to right, skipping global flags. Value-taking flags skip their value too, and the = form such as --workspace=/tmp is recognized.
3. Stop at the first token that is not a global flag. If it is one of go, run, once, hand argv to argparse unchanged; otherwise insert a go in front of it, so it becomes the body of go's request.
4. If the scan ends without hitting a positional (empty argv, or only global flags) → append go at the end and go to interactive input.
5. Exception: if argv contains -h or --help, return it unchanged and let argparse print help.

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

What the rewrite actually produces¶

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

Six usable forms¶

flower                                    # 1. Bare: asks "what do you want done?" or "continue from last time?"
flower "帮我做一个 X"                       # 2. Request as a positional argument
echo "帮我做一个 X" | flower --timeout 0    # 3. Feed stdin through a pipe
flower once "读一眼这个仓库"                 # 4. Single agent
flower run flows.py:main                  # 5. Run a custom workflow
flower go setup                           # 6. Explicit go, with setup as the request body

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() prints no prompt header and just does input("> ") to read one line (cli.py:993-1001). That is why echo "..." | flower works.

But a warning line follows, and the stdin thread immediately hits EOF and exits:

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

Piped runs should set --timeout 0: questions no longer pretend to wait 30 minutes, they fail immediately, the agent decides for itself and writes its assumptions into the "unknowns and assumptions" 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 "do X" goes through it.

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

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

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

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

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

The 11 flags of go¶

Edge cases in the values, none of which error or warn:

• --rounds 0 and --rounds 1 are equivalent — internally it is retries = max(0, rounds - 1), both run 1 round.
• Any negative --asks means unlimited, not just -1.
• Any negative --timeout equals 0, i.e. fully automatic.
• --window 0 is silently ignored (0 is falsy and never gets passed down), falling back to the default inferred from the model name. A negative value does get passed down and is then floored to 10000.
• --clarify-only is a no-op in a directory that has already been clarified — the 确认需求 step sees a complete 需求.md and skips, and since that is the only step in the workflow, nothing happens at all (except the wake count going up by 1). To re-clarify, combine it with --new.
• The --help of go ends with "全局开关(-v/-w/-r/-T)见 flower --help", and that 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 by module name
flower run flows.py:build        # file path; the parent directory is put on sys.path and imported by file name

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 ones. So --window, --no-handoff and friends always take their defaults on this path (the code falls back with getattr, cli.py:1041-1043). To adjust them, put the parameters into your own workflow.

once¶

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

It builds an AgentSpec(name="ad-hoc", …) and runs it directly, without going through _drive. So once has none of:

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

In the run manifest this step is always named ad-hoc.

setup¶

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

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

Global flags¶

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

The fact that -r/--run-dir is relative to CWD will bite: flower -w /other/proj "do X" creates runs/ in the directory you typed the command in, while .flower/ is created under /other/proj/ — the two pieces of state get separated. 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 enables in addition is:

• subagent body text (hidden by default, only its tool calls are shown)
• normal tool results (by default only the failing ones are shown)
• prompt events
• a dump of the effective credential configuration before startup, with tokens masked down to their first 4 characters

That last one goes through a bare print(), bypassing output sanitization, without wrapping, and unprotected by the terminal write lock — when several flower processes run in parallel these lines may be torn apart.

Talking to it while it runs¶

Once a run is going, the terminal is continuously reading your input. You do not have to wait for it to ask, and you do not have to press anything to enter an input mode — the last line is always the one you can type on.

The input prompt pinned to the bottom¶

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

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

On the display side, _say() is the single output channel; 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. The redraw also brings back the half-typed characters you have not yet entered — they live in _PROMPT["buf"] (cli.py:183-192). Without this the content would not actually be lost (it is still in the terminal's line buffer and Enter still sends it), but you could not see it, so you would doubt yourself and type it again.

The prompt has two texts, switching on whether a question is pending:

Character-by-character input mode and key bindings¶

To redraw the "half-typed characters", flower has to take over input itself. When stdin is a terminal and import termios works, the terminal is put into cbreak before the flower-stdin thread starts (cli.py:793-807) — cbreak rather than raw, so that Ctrl+C still produces SIGINT and the whole Ctrl-C machinery remains. It must be set before the thread starts: putting it inside the thread creates a real race, and characters typed in the instant before the thread gets the CPU are swallowed by line mode, which looks like "my input got lost" (reproduced reliably one time in three in testing, cli.py:928-934).

If it cannot be set, it falls back to the original whole-line readline() (non-terminal, termios unavailable, tcgetattr failure). Both paths work; line mode just lacks the key bindings 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 to a new line on screen — what you said stays above (cli.py:811-827).

Where what you type goes¶

When it goes into 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 only picks things up when it next checks the inbox on its own. The same sentence is also appended to notes/需求.md, since without spilling it would not survive a step boundary — the next step is a new session that only reads frozen artifacts.

A leading ? = 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 set to <run_dir>/aside/, so its cost and session lineage never 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 do not enter this window), each truncated to 200 characters, plus a description of the workbench paths.

It runs concurrently; the running run does not wait a single second. The answer looks like this:

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

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

What it says never enters the run's context — asking does not affect the run, and the answer is discarded right after.

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

What is 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 has crashed terminals twice.

  ? 这个工具要做成 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 final "还能问 N 次" line is not shown.

When a handoff writes the handoff document, it comes as 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 cannot see: every output line passes through sanitization that only lets flower's own SGR color codes through, while clear-screen and cursor-move sequences emitted by the model or tools are swallowed whole; and the width is max(40, min(terminal columns, 110)), so on wide terminals it deliberately does not fill the line.

The startup prompt¶

Running bare flower (with no request) asks first. Two texts:

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

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

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

This prompt reads via input(), without shell parsing. Chinese quotation marks, spaces and exclamation marks can be typed directly — that is the entire reason it exists. zsh, on hitting a Chinese closing quote, drops into dquote> continuation, which looks like a hang, when in fact nothing ever started.

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

Timeout¶

--timeout is a float in seconds, default 1800.0. Three kinds of value:

--timeout 0 and --timeout -1 are completely 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 text, in four variants:

Ctrl-C¶

Ctrl-C means completely different things in two places.

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

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

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

Pressing Enter here means interrupt without saying anything, and continue. If a question was pending at the time, an extra line is printed: (有 N 个提问还等着,打断不影响它们).

Pressing Ctrl+C again really exits, and as an uncaught KeyboardInterrupt — the screen will carry a Python traceback; it is not a clean exit.

Interruption is cooperative: it breaks cleanly at a message boundary and does not hard-cancel tasks. It does not count as a failed attempt and consumes no retries. On resume it attaches a note telling the model that "in-flight tool calls returning interrupted is a normal side effect of the interruption, not an environment failure".

This custom Ctrl-C handling is only installed when sys.stdin.isatty() (cli.py:1097). In a pipe, Python's default behavior remains, i.e. the first press exits. The once path does not 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: they first write the in-flight step into manifest.json marked killed-by-signal, then restore the default action and actually leave.

The reason: when a terminal crashes, the kernel sends SIGHUP, whose default action terminates the process outright — finally never runs, the manifest is never written, and a whole run's accounting is lost. On a non-OS main thread, or on a platform that does not support it, this is silently skipped.

First-run configuration flow¶

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

Gate one: are there credentials¶

It looks for credentials in priority order. If neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is found, the interactive configuration starts; in non-interactive mode (stdin is not a terminal) it does not 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 parts of this text do not match the implementation: the flower setup on the second line is currently unreachable (see setup); and the fourth line is the opposite of the code — flower does treat the env blocks of ~/.claude/settings.json and settings.local.json as a last-level fallback, borrowing only 9 credential keys from them and taking over no other setting. 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 wins: it does read them. The full lookup priority and those 9 keys are in 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 mandatory. Leave it blank and it prints the red line 没给 token,取消。 and gives up on configuring.
• Questions 2 and 3 may be left blank.
• When stdin is not a terminal, the whole flow is skipped without blocking.

Keys written out¶

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

Gate two: do the credentials work¶

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

Probe details: POST {BASE_URL}/v1/messages, max_tokens=16, default timeout 20 seconds, over stdlib urllib, with 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 could not even fit their thinking in, and the server struggled for 30 seconds before returning; with 16 it takes only 3.6 seconds.

The probe's conclusions fall into three categories of handling, and the differences matter:

The criteria for config have been tightened: Anthropic-style error JSON almost always contains the word model, so using that as "wrong model name" would misclassify a transient 400 as a configuration error and force a reconfiguration — it must explicitly say "not found / does not exist" to count (env.py:176-182).

The net rule is deliberate: a network hiccup should not force you to retype your token, and flower itself has machinery to suspend and reconnect when the network drops. Seeing "probe did not get through" needs no action; just keep running.

You get at most one reconfiguration chance. Failing a second time exits.

The probe only fires in an interactive terminal. ensure_credentials() returns immediately without making that 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 reasoning is that in non-interactive mode a detected problem cannot be fixed anyway, and the only effect would be "failing early" — and failing early is worse than not probing when it 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 a 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 starts the interactive configuration; once configured it prints:

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

Then it exits with code 1 regardless. The once path has none of this.

Exit codes¶

All the messages behind exit code 1:

At the end of a run (the go / run paths) a final line is printed:

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

This amount covers this process only, not the previous run — 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/¶

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 marks this process, in the format YYYYmmdd-HHMMSS-<6 hex digits>. The spill policy is append, do not overwrite: before every write it re-reads the file and deduplicates by run — rows belonging to this process are replaced by the latest ones, rows from other processes are left as they are.

Step names have four shapes:

When killed by a signal, the in-flight step is written in as well, with the error field set to 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, so two processes will clobber each other's lineage for identically named steps. To run in parallel, use different -r.

lineage.json stores the absolute path of the workspace. If it does not match, it is treated as absent and silently falls back to a new session, with no error — after the directory has been copied elsewhere, the old session_id could not be looked up anyway.

.flower/¶

The go path always generates these under notes/:

With --isolate the workbench moves outside the repository: <workspace>.parent/.flower-<workspace name>/. A worktree is each agent's private copy, while the workbench is a layer shared across agents, and shared things cannot live inside a private fence. In this case the workbench path given to the model is absolute.