CLI reference

This page documents the Daydream 0.27.0 command-line interface (CLI).

A pull request (PR) is a proposed change in a GitHub repository.

JavaScript Object Notation (JSON) is the structured data format used by command artifacts. An application programming interface (API) connects software to a service.

Command map

daydream [review] [TARGET] [OPTIONS]
daydream improve TARGET [OPTIONS]
daydream improve plan DESCRIPTION TARGET [OPTIONS]
daydream improve prune-reanchor NAME TARGET [OPTIONS]
daydream improve list-reanchor TARGET [OPTIONS]
daydream improve list-reanchored TARGET [--json]
daydream summarize PATH
daydream corpus harvest [OPTIONS]
daydream corpus build --out OUTPUT [OPTIONS]
daydream corpus label SESSION_PREFIX --outcome OUTCOME [OPTIONS]
daydream benchmark SUBCOMMAND [OPTIONS]
daydream post-findings ARTIFACT --pr PR --head-sha COMMIT_HASH --repo OWNER/REPOSITORY [OPTIONS]
daydream setup TARGET (--repo OWNER/REPOSITORY | --org ORGANIZATION) [OPTIONS]
daydream ext validate

daydream, daydream review, a leading option, and a repository path select the review command. A positive integer does not select a review target.

Use -h or --help for normal help. Use --help-all on the review command to show advanced options. Improve shows its shared advanced options in normal help.

Review

Syntax

daydream review REPOSITORY_ROOT [OPTIONS]

TARGET defaults to an interactive path prompt. The prompt default is the current directory. The target must be the exact root of a Git worktree.

Review modes

Option	Default	Behavior
No mode option	Deep review	Runs exploration, stack review, evidence checks, and merge. Daydream can post findings and apply fixes after confirmation.
--review	Off	Writes .review-output.md. Daydream does not run fix or test phases. An interactive run can offer to post the report to an open PR.
--comment	Off	Posts findings as a PR review. Daydream does not run fix or test phases.
--shallow	Off	Uses one stack assignment. Daydream skips cross-stack arbitration and merge. Daydream can apply fixes and run tests.

--review and --comment are mutually exclusive. --yes is not valid with either option.

--comment requires a resolvable PR. A missing PR or a posting failure returns status 1.

The default deep mode completes one review and fix pass. --yes accepts eligible gates for posting, fixing, committing, and report cleanup.

Public review options

Option	Value	Default	Description
--branch	BRANCH	Current local HEAD	Fetches the branch. Runs origin/BRANCH in a temporary detached worktree.
--base	BASE	Open PR base, then repository default branch	Sets the comparison point. Use a Git commit hash, tag, or branch name.
--shallow	None	Off	Selects the shallow review and fix flow.
-s, --stack	python, react, elixir, go, rust, or ios	Automatic detection	Forces one stack review.
-b, --backend	claude, codex, pi, or osprey	Configuration, then claude	Selects one backend for all phases.
-m, --model	MODEL	Configuration or phase default	Selects one model for all phases.
--reasoning-effort	EFFORT	Configuration or phase default	Selects one reasoning level for all phases. Backend support controls accepted values.
--review-profile	PATH	Configuration, then packaged default	Sets an explicit review profile file.
--yes	None	Off	Accepts eligible yes or no gates.
-h, --help	None	Off	Shows normal help.
--help-all	None	Off	Shows normal and advanced help.

Advanced review options

Option	Value	Default	Description
--log	None	Off	Writes raw agent events to standard output.
--worktree	None	Off	Runs the current HEAD in a temporary worktree.
--flow	NAME	Built-in flow from the mode	Selects a registered flow. Built-in aliases are deep, shallow, and review.
--precision	None	Configuration, then off	Enables precision mode for finding selection.
--approve-on-clean	None	Configuration, then off	Approves a PR with zero high- or medium-severity findings. Low or omitted severity permits approval. An unrecognized severity blocks approval.
--copy	PATH	Empty	Adds one workspace path to copy into a temporary worktree. Repeat the option for more paths.
--findings-out	PATH	Unset	Writes a findings artifact. Daydream stops before PR posting, fixing, and testing.
--pr-number	PR	Detected from the branch	Sets PR metadata for the trajectory and a findings artifact.
--cleanup	None	See cleanup rules	Removes .review-output.md after an eligible successful run.
--no-cleanup	None	See cleanup rules	Keeps .review-output.md.
--start-at	PHASE	review	Resumes at review, ttt, per-stack, merge, or fix when the selected flow supports that phase.
--ignore-path	PATH	Empty	Excludes a path from review. Repeat the option for more paths.

--flow cannot be combined with --review, --comment, or --shallow.

Every resume processes the exploration step first. The step reuses an exact cache or follows the exploration tier for the current diff. After exploration, ttt starts with intent analysis and alternative review. The per-stack point starts with stack-specific reviews. The merge point starts with existing parsed findings. The fix point starts with existing merged findings.

Daydream checks the required artifacts and the current diff before a resume. Daydream rejects a resume after other worktree changes.

Daydream rejects parse and test as resume points. Daydream also rejects ttt, per-stack, and merge with --shallow.

--findings-out is valid with --review and the default deep review. --findings-out is not valid with --comment or --shallow. The command requires a resolvable PR because the artifact must declare its target. Use --pr-number when automatic resolution is not available.

The default fix flow refuses to modify the checked-out base branch in place. Check out a feature branch. You can also use --branch or --worktree.

The cleanup flags control only .review-output.md. Cleanup runs only after exit status 0. A failed run keeps the report. --findings-out also keeps the report.

--cleanup removes the report, and --no-cleanup keeps the report. Without either flag, --yes removes the report. A non-interactive run keeps the report. An interactive run asks whether to remove the report.

Temporary worktree removal is independent of the cleanup flags. Daydream tries to remove a temporary worktree after each run. A removal failure can leave the worktree on disk.

Shared run and artifact options

Review and Improve commands can use the following shared options:

Option	Value	Default	Description
--trajectory	PATH	TARGET/.daydream/runs/SESSION_ID/trajectory.json	Sets the trajectory file.
--no-archive	None	Archive enabled	Disables the central archive copy in ~/.daydream/archive.
--no-eval	None	Evaluation enabled	Disables trajectory evaluation.
--dump-artifacts	DIRECTORY	Unset	Copies run artifacts to a directory.
--trajectory-hub-repo	REPOSITORY_ID	Configuration or environment	Uploads completed trajectory bundles to a Hugging Face dataset repository.
--non-interactive	None	Off	Selects default answers without prompts.

Daydream also enables non-interactive mode when standard input is not a terminal. A true continuous integration (CI) value enables the mode.

The --trajectory-hub-repo option has higher priority than DAYDREAM_TRAJECTORY_HUB_REPO and file configuration. Upload requires a Hugging Face token in HF_TOKEN. Upload failure produces a warning and does not change a successful command status.

Configure individual phases

The CLI has no phase-specific backend or model options. Set phase values in pyproject.toml or .daydream.toml. See Configuration.

Feedback

The feedback command is removed in this version. The self-hosted bot workflow handles bot review comments. See Self-hosted bot setup.

Improve

Improve performs a repository audit and writes implementation plans. Daydream requests read-only agent calls. Daydream writes Improve state under .daydream/improve and writes durable plans under daydream_plans. Configuration can also enable GitHub issue publication.

Audit syntax

daydream improve TARGET [OPTIONS]

Plan syntax

daydream improve plan DESCRIPTION TARGET [OPTIONS]

improve plan inspects the repository and writes one plan for the supplied description. improve plan does not run the category audit.

Improve options

Option	Value	Default	Description
--effort	quick, standard, or deep	standard	Selects the audit category set and work limits.
--focus	security, performance, tests, or branch	All categories	Limits the audit. branch audits changes after the current branch diverged from its base.
--scope	SERVICE_GROUP_OR_PATTERN	Whole repository	Limits work to a detected service, named group, or wildcard path pattern.
-b, --backend	Backend	Configuration, then claude	Selects one backend.
-m, --model	Model	Configuration or phase default	Selects one model.
--reasoning-effort	Effort	Phase configuration or built-in value	Selects one effort for all Improve phases.
--yes	None	Off	Has no effect on Improve. Use --non-interactive for unattended plan selection.
Shared run and artifact options	Various	See shared table	Controls trajectory, archive, evaluation, artifacts, upload, and unattended behavior.

quick audits correctness, security, tests, and technical debt. quick runs serially. It keeps high-confidence items and at most six items.

standard audits all eight categories. standard uses at most ten concurrent audit calls. The default configuration permits eight partition groups.

deep audits all eight categories. deep includes low-confidence items that need investigation. It uses at most ten concurrent audit calls. No default limits the partition groups.

A wildcard path pattern uses characters such as * to match paths. For example, services/* matches direct children of services.

Reanchor worktrees

prune-reanchor permanently removes one named temporary worktree. Run list-reanchor before you remove a worktree.

daydream improve prune-reanchor NAME TARGET
daydream improve list-reanchor TARGET
daydream improve list-reanchored TARGET [--json]

The named worktree must be in .daydream/worktrees. The worktree name must end in -reanchor. prune-reanchor returns status 0 when removal succeeds. The command returns status 1 for all other results.

list-reanchor lists existing -reanchor worktree names. An empty list returns status 0.

list-reanchored reads daydream_plans/.index.json. The command lists each plan number, title, status, and landing path. --json writes JSON instead of text. An empty index returns status 0.

prune-reanchor and list-reanchor accept the normal Improve options but do not use them. list-reanchored accepts only --json with its target.

An Improve audit or plan returns status 0 after complete work. The command returns status 1 after a failure or no plan. Partial GitHub issue publication returns status 2.

Summarize

Syntax

daydream summarize PATH

PATH can name a JSON trajectory file. It can also name a run directory with a trajectory and related artifacts. The command writes a Markdown summary to standard output.

The command returns status 0 on success. The command returns status 1 for a missing or invalid path. Status 2 means that all available trajectory inputs failed to parse.

Corpus

daydream corpus without a subcommand returns status 2.

Harvest

daydream corpus harvest [OPTIONS]

The command reads completed runs from the archive index. It computes one current label observation for each selected run. The command appends an observation when the evidence or reward version is new.

Option	Value	Default	Description
--dry-run	None	Off	Computes observations without appending them to the archive index.
--session	PREFIX	All sessions	Includes archive session IDs that start with the prefix.
--cache-dir	PATH	~/.daydream/harvest-cache	Sets the harvest cache.
--archive-dir	PATH	DAYDREAM_ARCHIVE_DIR, then ~/.daydream/archive	Sets the archive source.
--repo-clone-root	PATH	CACHE_DIR/repos	Sets the clone cache for source repositories.
--gh-spacing-sec	SECONDS	0.8	Sets the delay after each successful non-dry-run archive row. The value must be zero or greater.

--dry-run does not append label observations or update PR links. The command can still update repository clones and response caches. It can also add a missing base commit hash to an archive manifest.

An error for one archive row does not fail the command. Invalid option values return status 1. Invalid syntax returns status 2.

Build

daydream corpus build --out OUTPUT_JSONL [OPTIONS]

Option	Value	Default	Description
--out	PATH	Required	Sets the output JSON Lines file.
--skill	SKILL	All skills	Keeps rows with an exact manifest skill.
--repo	OWNER/REPOSITORY	All repositories	Keeps one repository. Repeat the option to select more repositories.
--label	LABEL	accepted	Keeps one human outcome label. Repeat the option to select more labels.
--include-all-labels	None	Off	Includes all labels. --include-all-labels conflicts with --label.
--min-grounding	FLOAT	Unset	Sets a grounding score floor from 0 through 1.
--min-reward	FLOAT	Unset	Keeps a row when its stored composite reward meets the minimum. The row does not need the accepted label.
--status	STATUS	complete	Keeps one run status.
--stratify-by	stack	Unset	Groups output by stack and applies the stack share limit.
--max-stack-share	FLOAT	0.6	Caps each stack at the input count times this value. The value must be greater than 0 and at most 1.
--allow-copyleft	OWNER/REPOSITORY	Empty	Allows one copyleft repository. Repeat the option to allow more repositories.
--dry-run	None	Off	Reports selection counts without writing data files.
--emit-schema-only	None	Off	Writes schema.json without writing the JSON Lines file. Removes an existing lineage.json.
--as-of	UTC_TIMESTAMP	Latest data	Builds from the corpus state at a Coordinated Universal Time (UTC) timestamp. Use Z or +00:00.

A normal build replaces the selected JSON Lines file atomically. Every normal build writes schema.json. A nonempty build writes lineage.json. An empty build removes an existing lineage.json. Validation failure returns status 1. Invalid syntax returns status 2.

Label

daydream corpus label SESSION_PREFIX --outcome OUTCOME [--archive-dir ARCHIVE_DIR]

--outcome is required. Valid values are accepted, contested, rejected, and unknown. --archive-dir defaults to DAYDREAM_ARCHIVE_DIR, then ~/.daydream/archive.

The session prefix must match exactly one archived session. The command records a human outcome label. A human label has priority over computed labels. No match or multiple matches return status 1. Invalid syntax returns status 2.

Benchmark

The benchmark command has these subcommands: init, status, validate, build-harbor, upgrade, import-prs, curate, calibrate-judge, run, clean, objective, and aggregate. The legacy daydream bench verb is not a command. The benchmark runs a private Harbor workspace. See Benchmarking for the full command surface, options, and exit statuses.

Post findings

Syntax

daydream post-findings ARTIFACT \
  --pr PR \
  --head-sha COMMIT_HASH \
  --repo OWNER/REPOSITORY \
  [OPTIONS]

post-findings checks a saved findings artifact before any GitHub write. The artifact must use schema version 1. The artifact must not exceed one mebibyte (MiB). The command compares the artifact repository, PR, and head commit with the supplied target values. The command compares findings with prior bot comments. The command then posts only new findings.

Option	Value	Default	Description
--pr	Positive integer	Required	Selects the PR.
--head-sha	Full commit hash	Required	Requires the artifact head commit to match this caller-supplied commit.
--repo	OWNER/REPOSITORY	Required	Selects the GitHub repository.
--bot-login	LOGIN	DAYDREAM_BOT_HANDLE	Selects the bot identity used to recognize prior comments.
--approve-on-clean	None	Configuration, then off	Approves the PR with zero high- or medium-severity findings. Low or omitted severity permits approval. An unrecognized severity blocks approval.

If Daydream cannot resolve a bot login, prior-comment checks are less precise. Daydream warns that duplicate comments are possible. Invalid configuration syntax produces a warning. The command then uses default configuration.

No new findings returns status 0. A file check, target check, comparison, or posting failure returns status 1. Invalid syntax returns status 2.

Posting is not atomic. File comments can exist when final PR review creation fails.

Setup

Syntax

daydream setup TARGET (--repo OWNER/REPOSITORY | --org ORGANIZATION) [OPTIONS]

The command configures the Daydream GitHub App for one repository or organization.

Option	Value	Default	Description
--repo	OWNER/REPOSITORY	Mutually required	Selects one repository.
--org	ORGANIZATION	Mutually required	Selects one organization.
--verify	None	Off	Runs a read-only configuration check.
--force	None	Off	Registers the app again when credentials already exist.

Select exactly one of --repo and --org. --force has no effect with --verify. A successful setup or verification returns status 0. A setup or verification failure returns status 1. Invalid syntax returns status 2.

Extension validation

Syntax

daydream ext validate

The command loads the configured extension API package. The package must use API version 6. The command also checks registered phases, flows, skill slots, prompts, and a tool supervisor.

Set DAYDREAM_EXT_DIR to load an extension directory first. Without DAYDREAM_EXT_DIR, Daydream tries the daydream_ext Python package. The command can run without an installed extension. In that case, the command checks only built-in registrations.

The command returns status 0 for valid registrations. It returns status 1 for a load or validation error. A missing, unknown, or malformed subcommand returns status 2.

Exit status summary

Status	Meaning
0	Success. A declined optional action, no diff, no actionable feedback, or no new finding can also be successful.
1	Runtime, validation, Git, agent, test, or posting failure. Command sections document exceptions.
2	Invalid CLI syntax or a missing subcommand. Improve also uses status 2 for partial GitHub issue publication.
130	The process received an interrupt or termination signal.

Argument parser errors return status 2. An uncaught command error returns status 1.

Source

The command definitions are in daydream/cli.py and daydream/benchmark/cli.py.

Back to Daydream