DeepFlow CLI

Zero-dependency CLI wrapper for DeepFlow Web methods.

Install

npm install -g @metagptx/deepflow-cli
deepflow --help
deepflow -l -t <dfpat_token> --base-url https://deepflow.example.com

During interactive npm install, the package prompts whether to install the DeepFlow CLI assistant skill into Codex, Claude Code, both, or neither. The skill teaches agents when to use deepflow for task pool, iteration, workspace, and plan/session automation.

For non-interactive installs, use an environment variable:

DEEPFLOW_CLI_INSTALL_SKILL=all npm install -g @metagptx/deepflow-cli
DEEPFLOW_CLI_INSTALL_SKILL=codex npm install -g @metagptx/deepflow-cli
DEEPFLOW_CLI_INSTALL_SKILL=claude npm install -g @metagptx/deepflow-cli
DEEPFLOW_CLI_SKIP_SKILL_INSTALL=1 npm install -g @metagptx/deepflow-cli

You can also install or update the skill later:

deepflow skill install --target all
deepflow skill install --target codex
deepflow skill install --target claude

npx is still useful for one-off execution, but it does not install deepflow into your PATH for later shell sessions:

npx @metagptx/deepflow-cli --help
npx --package @metagptx/deepflow-cli deepflow --help

For local development from this repository:

npm link
deepflow --help
node bin/deepflow.js --help

Authenticate

deepflow -l -t <dfpat_token>

To record a custom caller source in DeepFlow Web token call logs:

deepflow -l -t <dfpat_token> --source ci
deepflow --source ci iterations create --name "Demo" --repo <repo_id_or_app_code>

Equivalent forms:

deepflow -login -t <dfpat_token>
deepflow --login -t <dfpat_token>
deepflow auth login -t <dfpat_token>

Config is stored at:

~/.deepflow/config.json

The default call source is deepflow-cli. You can override it with --source <name>, DEEPFLOW_SOURCE, DEEPFLOW_CLI_SOURCE, or a saved profile value from auth login --source <name>.

Project-scoped DeepFlow deployments require a project key. Set it explicitly so create/list requests and generated UI links stay in the intended workspace:

export DEEPFLOW_PROJECT_KEY=atoms
# or per command
deepflow --project-key atoms iterations list

Run Plan

deepflow plan run \
  --repo <repo_id_or_app_code> \
  --name "Demo Iteration" \
  --context "Plan this change" \
  --prompt "Create an implementation plan only." \
  --json

plan run --json returns statusUrl, messagesUrl, and stopUrl so external callers can poll or stop the created session without knowing DeepFlow Web route details.

Execute And CR

deepflow execute run \
  --iteration <local_iteration_id> \
  --repo <repo_id_or_app_code> \
  --prompt "Apply the required implementation." \
  --json

deepflow execute status \
  --iteration <local_iteration_id> \
  --session <session_id> \
  --json

deepflow cr run \
  --iteration <local_iteration_id> \
  --repo <repo_id_or_app_code> \
  --prompt "Review the changes and return approved or needs_revision." \
  --json

deepflow cr status \
  --iteration <local_iteration_id> \
  --session <session_id> \
  --json

execute and cr now use the same session + message flow as plan. For backward compatibility, execute status and cr status still accept --job-id, but the value is now the session id.

When a DeepFlow Web deployment does not expose CR sessions on /api/local/sessions, cr run automatically falls back to /api/local/cr-jobs. In fallback mode it returns both the local CR jobId for cr status --job-id and the Core review sessionId for session inspection.

Repo Submit returns an asynchronous execution job. Poll the returned jobId until it reaches done (or a failure status); the terminal response includes the MR URL and published commit SHA:

deepflow submit-repo --iteration <local_iteration_id> --repo <repo_id> --request-id <stable_id> --json
deepflow execution-job get --job-id <repo_submit_job_id> --json

Persist the stable request ID before submitting and reuse it after a timeout or restart. DeepFlow returns the original job instead of creating a duplicate delivery for the same iteration, repository, and request ID.

Task Pool

deepflow tasks list --kind all
deepflow requirements create --title "Fix login callback" --kind bug --priority high --repo <repo_id_or_app_code>
deepflow requirements update --id <requirement_id> --status planned
deepflow requirements create-iteration --id <requirement_id> --name "Login callback fix" --repo <repo_id_or_app_code>

deepflow discoveries list
deepflow discoveries create --name "New onboarding" --idea-file ./idea.md --design-branch project/onboarding --code-repos 123,456
deepflow discoveries create-iteration --id <discovery_id> --name "Build onboarding" --repo <repo_id_or_app_code>

Iterations

deepflow iterations list
deepflow iterations get --iteration <local_iteration_id>
deepflow iterations create --name "Demo Iteration" --repo <repo_id_or_app_code> --context "Implement this change"
deepflow iterations update --iteration <local_iteration_id> --stage plan --status doing
deepflow iterations add-repo --iteration <local_iteration_id> --repo <repo_id_or_app_code>
deepflow iterations delete --iteration <local_iteration_id>

deepflow iterations inspect --iteration <local_iteration_id> --json
deepflow iterations plan-start --iteration <local_iteration_id> --repo <repo_id> --prompt "Create a plan" --request-id <id> --json
deepflow iterations plan-decide --iteration <local_iteration_id> --session <session_id> --request-id <ExitPlanMode_request_id> --action review --json

Orchestration Agent (0.3.0)

dfagent_ tokens are supported alongside personal dfpat_ tokens. When DEEPFLOW_SESSION_ID is present, every request automatically includes the current orchestration Session identity.

deepflow plan-review start --iteration <id> --repo <repo_id> --session <plan_session_id> --plan-record <id> --request-id <id> --json
deepflow plan-review status --run-id <run_id> --json
deepflow plan-review stop --run-id <run_id> --json
deepflow session list --iteration <id> --json
deepflow session clarify --iteration <id> --session <session_id> --request-id <clarification_request_id> --answers '{"<question text>":"<answer>"}' --json
deepflow cr repair --job-id <cr_job_id> --strategy new --plan-record <id> --request-id <id> --json
deepflow agent record --action-id <id> --step observe --summary "Inspected Iteration" --json

iterations inspect exits with code 7 and errorCode=decision_unsafe when the snapshot is incomplete. All write commands accept stable request IDs so a caller can safely retry the same intent.

Agent action statuses are stored as started, succeeded, or failed. For compatibility, --status pending and --status running are normalized to started. Failed Plan Review retries must reuse the requestId returned by iterations inspect; the Web service limits a Review Run to three retries.

Workspace

deepflow workspace tree --iteration <local_iteration_id> --repo <repo_id_or_app_code>
deepflow workspace read --iteration <local_iteration_id> --repo <repo_id_or_app_code> --path README.md
deepflow workspace write --iteration <local_iteration_id> --repo <repo_id_or_app_code> --path notes/demo.md --content-file ./demo.md
deepflow workspace mkdir --iteration <local_iteration_id> --repo <repo_id_or_app_code> --path notes
deepflow workspace rename --iteration <local_iteration_id> --repo <repo_id_or_app_code> --from notes/demo.md --to notes/final.md
deepflow workspace delete --iteration <local_iteration_id> --repo <repo_id_or_app_code> --path notes/final.md --force
deepflow workspace package-url --iteration <local_iteration_id> --repo <repo_id_or_app_code>

Checks

npm run check
npm test
npm run smoke
npm run pack:dry-run

Run the full Web-backed smoke when a token and app are available:

DEEPFLOW_CLI_E2E_TOKEN=<dfpat_token> \
DEEPFLOW_CLI_E2E_BASE_URL=http://localhost:3100 \
npm run smoke:e2e

Useful environment variables:

export DEEPFLOW_BASE_URL=http://localhost:3100
export DEEPFLOW_TOKEN=dfpat_xxx
export DEEPFLOW_SOURCE=ci

Publish

Validate the package contents before publishing:

npm run check
npm test
npm run smoke
npm run pack:dry-run

Publish to the configured npm registry:

npm publish --access public

For a private company registry, pass the registry explicitly:

npm publish --registry <registry-url>