Every kirocrew subcommand, grouped by what it does. Run kirocrew <cmd> --help for the authoritative flag list on your installed version — this page reflects the current shape.
Applies to every subcommand.
| Flag | Purpose |
|---|---|
--port <n> | Override the gateway port (default: KIROCREW_PORT or 5476) |
--home <path> | Override the data home (default: KIROCREW_HOME or ~/.kiro/crew) |
--verbose | Increase logging verbosity |
--help | Show help for the subcommand |
--version | Print kirocrew version and exit |
Environment variables the CLI respects:
| Variable | Default | Purpose |
|---|---|---|
KIROCREW_HOME | ~/.kiro/crew | Data directory |
KIROCREW_PORT | 5476 | Gateway port |
KIROCREW_EMBED_MODEL_URL | (CDN) | Override embedding-model download URL |
KIROCREW_ALLOW_UNSANDBOXED | (unset) | In Docker, explicitly allow agent exec without the inner sandbox |
Interactive wizard. Prompts for data directory, agent backend, and (optionally) Slack tokens. Skip Slack tokens to run in dashboard-only mode.
kirocrew setup kirocrew setup --agent-only # only redo the agent config kirocrew setup --agent-only --clean # nuke and rebuild MCP config
Health check. Reports the status of every subsystem:
kiro-cli binary discovery and loginStart the server. Blocks in the foreground until Ctrl+C.
kirocrew gateway # → http://localhost:5476 kirocrew gateway --port auto # OS-assigned port; prints KIROCREW_READY:{...} kirocrew gateway --port 6777 # custom port kirocrew gateway --no-crons # skip the cron scheduler (multi-instance setups) kirocrew gateway --test-mode # ephemeral port + json-ready + reads-only approval kirocrew gateway --approval reads # auto-approve read-only tools kirocrew gateway --approval yolo # auto-approve ALL tools (requires non-default KIROCREW_HOME)
Stop or restart the running gateway. Atomic on systemd; unload + load on launchd.
Tail live gateway logs.
kirocrew logs # last 200 lines kirocrew logs -f # follow kirocrew logs -n 500 # last 500 lines
Register as a system service so the gateway survives SSH disconnects and auto-restarts on crash.
kirocrew service install # systemd (Linux) or launchd (macOS) kirocrew service status kirocrew service uninstall
Self-update. git pull + rebuild + pip install -e . + execv restart.
Mint a short-lived dashboard login link. Print the URL.
kirocrew token --ttl 2h # 2-hour token kirocrew token --port 6777 # for a specific gateway port
Interactive REPL or one-shot.
kirocrew chat # REPL kirocrew chat "one-shot query" # one-shot; prints response kirocrew chat --agent reviewer # use a named agent kirocrew chat --json # machine-readable output echo "prompt" | kirocrew chat # headless stdin
Slash commands inside the REPL: /compact, /model, /incognito, /clear, /help, /exit.
Run a task from a spec file.
kirocrew run TASK.md # auto-resume from checkpoint kirocrew run TASK.md --fresh # ignore checkpoint, start over kirocrew run TASK.md --no-test # skip test verification kirocrew run TASK.md --timeout 3600 # global timeout kirocrew run TASK.md --agent <name> # use a named agent
Show status of active task runs.
Cancel a task run.
kirocrew run cancel <task_id> # specific task kirocrew run cancel # all running tasks
Create a scheduled job.
kirocrew cron add "name" "prompt" --cron "0 9 * * 1-5" kirocrew cron add "name" "prompt" --every 300
Flags:
| Flag | Purpose |
|---|---|
--cron "<expr>" | Standard cron expression (mutually exclusive with --every) |
--every <secs> | Interval in seconds |
--timezone "<tz>" | Per-job timezone (IANA name; defaults to the configured global timezone, then UTC; refused with --every) |
--skip-dates "YYYY-MM-DD,..." | Exclude specific dates |
--timeout-secs <n> | Per-job timeout in seconds (1 to 86400; default 1800) |
--agent <name> | Agent to run under |
--persistent-session | Reuse the same session across runs |
--silent | No notification unless the agent sends one |
--strict-schedule | Disable execution jitter |
--managed-by <key> | Register the job under an owner key for an external installer (for example mysystem:owner/asset-name). The key is unique across the store; a second add with the same key is refused. Reinstall with cron remove --managed-by <key>, then add again |
kirocrew cron list kirocrew cron remove <job_id> kirocrew cron remove --managed-by <key> # remove the job registered with that key kirocrew cron remove-all kirocrew cron pause <job_id> kirocrew cron resume <job_id> kirocrew cron trigger <job_id> # run once manually kirocrew cron update <job_id> --cron "0 10 * * *"
cron remove takes either a job id or --managed-by <key>, not both.
Spawn a background subagent.
kirocrew spawn run "check my open CRs" # blocking kirocrew spawn run --async "check CRs" # fire-and-forget kirocrew spawn run --agent reviewer "review X" kirocrew spawn run --cwd /path/to/project "..." # subagent runs in a specific dir
List active subagents with IDs, status, and elapsed time.
Add a lesson injected into every future session.
kirocrew learn add "always use TypeScript over JavaScript" kirocrew learn add "prefer pytest over unittest" --category tool kirocrew learn add "use exact-match on strings" --scope workspace
Categories: general, tool, style, workflow. Scopes: global (default), workspace.
kirocrew learn list kirocrew learn list --category tool kirocrew learn remove "prefer pytest"
Create the directory of a named memory store declared in config.json under memory_stores. A declared store is never created on first use, so a store whose directory was deleted stays missing until this command runs.
kirocrew memory create-store research
Prints Created memory store 'research' at <path>. or, when the directory already exists, Memory store 'research' already exists at <path>; nothing changed. The command refuses the default store (which needs no create step), a name not declared under memory_stores, and a crewmate's store (created with its crewmate); a refusal prints one line on stderr and exits 1.
Other kirocrew memory verbs at this version: list, search, show, stats, audit, export, migrate, backup, backups, restore, carve, retired, and import. Run kirocrew memory --help for their flags.
Create a tarball backup of all state.
kirocrew snapshot # → ~/.kiro/crew/snapshots/ kirocrew snapshot ~/my-snapshots # custom dir kirocrew snapshot ~/my-snapshots --keep 3 # prune to 3 most recent kirocrew snapshot --list # list existing snapshots
Restore from a tarball.
kirocrew restore snapshot.tar.gz # auto-detect replace vs merge kirocrew restore snapshot.tar.gz --mode replace kirocrew restore snapshot.tar.gz --components memory,crons kirocrew restore snapshot.tar.gz --dry-run kirocrew restore --list-components # show valid components
kirocrew config get # print full config kirocrew config get agent.sandbox # print one key kirocrew config set dashboard.bot_name "X" # set a key kirocrew config unset dashboard.bot_name # remove a key kirocrew config edit # open in $EDITOR
Review stored values that still match a superseded default after an upgrade. Use --adopt to remove those stored values so the current defaults apply, or --keep to mark the stored values as intentional.
kirocrew config defaults kirocrew config defaults --adopt kirocrew config defaults --keep session.autocompact_pct
Toggle live-reload dev mode for an installed app.
kirocrew app dev my-app # turn on kirocrew app dev my-app --off # turn off # Required when ui/ resolves outside the installed app directory: kirocrew app dev my-app --confirm-out-of-install-root
In dev mode, the gateway watches the app's ui/ directory and broadcasts an app_reload WebSocket event on any file change. The dashboard reloads the app immediately.
Convert a manifest-based plugin package from another agent harness into a Crew app directory. The converter copies recognized resources, reports anything it cannot map, and never executes package code.
kirocrew app import <package-dir> kirocrew app import <package-dir> --out <dir> --name <name> kirocrew app import <package-dir> --install
Without --out, the converted app is written to ./<app-name>-app. --install runs the ordinary local app install after conversion; enable the installed app separately.
Use --slug when you need an exact artifact handle. A malformed or already-taken explicit slug is refused. Omit --slug to derive one from --name; a derived collision receives a numeric suffix instead.
kirocrew artifact save --name "Release notes" --slug release-notes --content-file notes.md
Read library counts without running a migration or repair:
kirocrew knowledge stats kirocrew knowledge stats --json
The output includes total and per-source document and item counts.
Generate a Slack app manifest.
kirocrew manifest # print YAML manifest to stdout kirocrew manifest --url # print a Slack "Create New App from manifest" URL kirocrew manifest -o slack.yaml # write manifest to a file
Runtime stats summary — message counts, tool calls, session metrics, subagent spawns.
kirocrew status kirocrew status --json
Run the multi-session evaluation harness.
kirocrew eval # smoke test kirocrew eval --all # every scenario kirocrew eval --scenario <name> # single scenario
Requires kirocrew gateway --test-mode running in another shell.
List apps addressable by the computer-use MCP tools (macOS only).
Human debug harness for computer-use tools. Runs the ten computer_* MCP tools through the same gated chokepoint. Not intended for LLM callers.
kirocrew computer call computer_list_apps kirocrew computer call --calls '[{"tool":"computer_click","args":{...}}]'
Inside a running Docker container:
docker exec kirocrew kirocrew token --ttl 2h # mint a login link docker exec -it kirocrew kiro-cli login # log in the agent runtime docker exec -u 0 kirocrew chown kirocrew:kirocrew <path> # fix ownership after docker cp
Invalidate the current dashboard token.
kirocrew setup && kirocrew doctor && kirocrew gateway
kirocrew setup --agent-only --clean
# on source kirocrew snapshot ~/migrate # copy tarball to new machine, then: kirocrew restore ~/migrate/snapshot-*.tar.gz kirocrew doctor
kirocrew service install kirocrew token --ttl 20h # open the printed URL on your local machine (via SSH tunnel or reverse proxy)
| Code | Meaning |
|---|---|
0 | Success |
1 | Generic error |
2 | Invalid arguments |
3 | Gateway not running (for CLI commands that need it) |
10 | Health-check failure (kirocrew doctor) |
Use a pod to run a Kiro Crew source worktree with its own Gateway, data home, port, and process boundary. Crew uses a per-user service manager on each supported platform: systemd --user on Linux, launchd on macOS, and Task Scheduler on Windows. On Windows, the current user must be allowed to create a scheduled task.
| Command | Purpose |
|---|---|
kirocrew pod provision <worktree> | Build the worktree virtual environment and dashboard assets |
kirocrew pod up <worktree> | Start or reuse the isolated pod |
kirocrew pod up <worktree> --provision | Provision, then start |
kirocrew pod ls | List running pods and orphaned pod homes |
kirocrew pod status <worktree> | Show lifecycle and health |
kirocrew pod token <worktree> | Mint a dashboard token |
kirocrew pod url <worktree> | Print the pod base URL |
kirocrew pod logs <worktree> -n 50 | Read recent pod logs |
kirocrew pod down <worktree> | Stop the pod and remove its isolated home |
kirocrew pod prune --dry-run | Preview bulk cleanup of orphaned pod homes |
kirocrew pod api <worktree> GET <path> | Make one authenticated API request to a running pod |
pod api sends its request over the pod's private Unix-domain socket and is not available on Windows. Use pod token and the printed URL with your own HTTP client instead.
kirocrew cloud provisions and runs Kiro Crew on an EC2 instance in your own AWS account. Its subcommands are launch, list, status, connect, tunnel, login, logout, stop, start, destroy, iam-policy, iam-boundary, and doctor. Run kirocrew cloud --help for each one's flags; this section covers launch.
Provision and configure an instance, then open the dashboard.
kirocrew cloud launch # interactive kirocrew cloud launch --size power # pick a size tier without prompts kirocrew cloud launch --new # create a separate new instance kirocrew cloud launch --extra-packages gh,jq # also install these dnf packages kirocrew cloud launch --ami ami-0abc1234 # launch from your own AL2023-based image
| Flag | Purpose |
|---|---|
--size <tier> | Instance size tier (default: balanced, or the interactive picker) |
--subnet <SUBNET_ID> | Launch into this exact subnet (subnet-xxxx) instead of network auto-discovery; it needs internet egress |
--ami <AMI_ID> | Launch from this AMI (ami-xxxx) instead of the latest Amazon Linux 2023 image. It must match the size tier's architecture and be AL2023-compatible |
--extra-packages <PKGS> | Extra dnf packages to install on the instance, comma-separated (for example gh,jq). A package dnf cannot find is skipped with a warning in the setup log |
--new | Create a separate new instance instead of resuming the saved one |
-y, --yes | Accept defaults, no prompts |
For --extra-packages, a name may use letters, digits, and . _ + -, must start with a letter or digit, and the joined list may not exceed 256 characters. Duplicates are dropped.
kirocrew --help — top-level command listkirocrew <cmd> --help — subcommand-specific helpkirocrew doctor --verbose — full diagnostic output
CLI reference