Skip to content

CLI reference

All commands are available as developer <command> (with venv activated) or uv run developer <command>.

--config PATH, given before the command, chooses the developer.yaml to use (developer --config ~/dev/developer.yaml review myrepo 5). Without it, Developer uses $DEVELOPER_CONFIG, then ./developer.yaml, then the one at the project root. Clones, run records and .env live beside that file; see configuration.

resolve

developer resolve REPO ISSUE_NUMBER [--dry-run]

Resolve a GitHub issue. Triages it, then comments, opens a PR recording a decision, or implements the fix step by step and opens a PR.

Arguments:

  • REPO -- repo name from developer.yaml, or a GitHub issue URL
  • ISSUE_NUMBER -- issue number (omit if using a URL)

URL formats:

developer resolve assistant 25
developer resolve https://github.com/gregology/assistant/issues/25
developer resolve github.com/gregology/assistant/issues/25
developer resolve gregology/assistant/issues/25

When using a URL, the repo name is matched against your developer.yaml config by the GitHub owner/repo pair.

Flags:

Flag Description
--dry-run Run the whole pipeline, then print the PR and its diff instead of pushing

review

developer review REPO PR_NUMBER [--dry-run]

Review a pull request. Analyzes the diff, generates findings, posts a comment.

Arguments:

  • REPO -- repo name from developer.yaml, or a GitHub PR URL
  • PR_NUMBER -- PR number (omit if using a URL)

URL formats:

developer review assistant 42
developer review https://github.com/gregology/assistant/pull/42
developer review github.com/gregology/assistant/pull/42
developer review gregology/assistant/pull/42

Flags:

Flag Description
--dry-run Print the review comment to stdout instead of posting

address

developer address REPO PR_NUMBER [--dry-run]

Address review feedback on a PR. Fetches comments, identifies actionable items, implements changes, pushes.

Arguments:

  • REPO -- repo name from developer.yaml, or a GitHub PR URL
  • PR_NUMBER -- PR number (omit if using a URL)

URL formats: same as review.

Flags:

Flag Description
--dry-run Run the whole pipeline, then print the reply and the diff instead of pushing or commenting

audit

developer audit TYPE REPO [--dry-run] [--limit N]

Audit a repo. Creates GitHub issues for findings.

Types:

  • docs -- check documentation for drift from the codebase
  • refactor -- identify refactoring opportunities using quality tool output
  • tests -- evaluate test coverage against risk

Arguments:

  • TYPE -- one of docs, refactor, tests
  • REPO -- repo name from developer.yaml

Flags:

Flag Description
--dry-run Print findings to stdout instead of creating issues
--limit N Max number of findings (default 3)

validate

developer validate [REPO] [--all]

Validate a repo's configuration by cloning from scratch into a temp directory, setting up a worktree exactly as a run does, running quality tools, and tearing down. Reports pass/fail for each step.

Arguments:

  • REPO -- repo name from developer.yaml (required unless using --all)

Flags:

Flag Description
--all Validate every repo in developer.yaml

doctor

developer doctor [--online]

Check that this machine can run Developer: the Claude CLI and its login, the Bash sandbox prerequisites (bubblewrap, socat, and on Ubuntu 24.04+ an AppArmor profile for bwrap), git, developer.yaml, the repos directory and the GitHub App credentials. Prints a fix for anything missing and exits with status 1 if any check fails.

Flag Description
--online Also authenticate the GitHub App against GitHub, and check it's installed where it can reach every repo in developer.yaml

add

developer add OWNER/REPO [--dry-run]

Investigate a repo and add it to developer.yaml. Clones the repo, runs an agent to discover setup and teardown commands, testing philosophy, and quality tools, then writes the discovered config.

Arguments:

  • OWNER/REPO -- GitHub owner and repo name (e.g. gregology/assistant)

Flags:

Flag Description
--dry-run Print discovered config without saving to developer.yaml

serve

developer serve [--host HOST] [--port PORT] [--allow-insecure]

Start the Developer API server. Exposes the same pipelines as the CLI over HTTP so a UI or other tooling can drive them. Needs the api extra (uv sync --extra api). With DEVELOPER_API_TOKEN set, requests must carry it as a bearer token; without one, the server only binds to loopback addresses unless started with --allow-insecure.

Flags:

Flag Description
--host HOST Bind address (default 127.0.0.1)
--port PORT Bind port (default 6768)
--allow-insecure Serve beyond loopback without DEVELOPER_API_TOKEN, when something else controls who can reach the port

Pipeline endpoints (/resolve, /review, /address, /audit/{type}, /validate, POST /repos) accept JSON bodies and return a task_id immediately. Poll GET /tasks/{task_id} for status, logs, and results. See API reference for the full endpoint list.

Exit codes

All commands return 0 on success and non-zero on failure. Config errors, missing repos, and GitHub API failures all produce non-zero exits with descriptive error messages.