Kirocrew Commands

Kiro Crew CLI Reference

Setup & System

update --force is destructive on a git install: the hard reset discards local commits, recoverable only from git reflog. The sandbox verbs matter only on hosts with kernel.apparmor_restrict_unprivileged_userns=1 (Ubuntu 23.10+ and derivatives) and are no-ops everywhere else; --path is refused for world-writable locations and for shared interpreters such as /usr/bin/python3, which would over-grant.

Gateway (Server)

The token in a --json-ready line grants dashboard access for up to 20 hours, so captured stdout from a test harness is a credential: keep it out of logs and transcripts.

Service Management

Pods (Isolated Worktree Test Instances)

Ephemeral, full-stack Kiro Crew gateways — one per feature worktree — that run on their own port + isolated KIROCREW_HOME and never touch the live :5476 gateway or shared data. Linux systemd --user only. <wt> is a worktree name (resolved by directory basename or feat/<name> branch convention).

Platform: Linux only. On macOS/Windows every systemd-touching verb refuses with a one-line message pointing at ./dev-backend.sh — it does not crash, and pod install writes no unit file. pod url works anywhere (pure computation).

Port derivation: base + (cksum(name) % 199) + 1 (base 7810 → 7811..8009). Override with PORT= in ~/.kiro/crew/pods/<name>.env.

kirocrew pod --help lists every verb and its flags.

Dashboard Access

Chat

Browsing (browser MCP tool, then playwright-cli)

Browsing is not a kirocrew subcommand. Start with the browser MCP tool in the native Browser panel: op=navigate|snapshot|click|type|press_key|hover|select_option|screenshot|wait_for|back|console. It refuses loopback, private, and link-local targets. Use playwright-cli when no native panel serves the session, or for attached logins, saved storage state, and the full operate verbs. It must be on PATH; install via Settings → Browser (also holds the attach token) or npm install -g @playwright/cli@latest (Node.js 20 or newer).

Browsing workflow: load the web-browse, web-verify, or browser-auth skill for the task. On the CLI path:

1. Check command -v playwright-cli; if absent, use web_fetch and give the install command above.
2. Run playwright-cli open <url>; read its snapshot YAML only when the tree is needed, such as before clicking. Refs ([ref=e5]) expire on page changes: re-snapshot before the next action.
3. On a login redirect, state-load a saved session or let the user sign in in the Browser panel, then state-save.

No npm access (internal registry, air-gapped host): detection is PATH-based -- playwright-cli on PATH is all that matters, so ANY install route works and the Settings button is a convenience, not the only one. In order of likelihood:

1. Most internal registries proxy npmjs, so the plain install already works.

2. Force the public registry for this one package: npm install -g @playwright/cli --registry=https://registry.npmjs.org.

3. An internal registry that requires a login the user does not have (the common Amazon-internal / corporate case). Install into a user-owned prefix against the public registry, ignoring the corporate .npmrc for this one command, then put the binary on PATH:

   NPM_CONFIG_USERCONFIG=/dev/null \
     npm install --prefix ~/.local/share/playwright-cli \
     --registry=https://registry.npmjs.org @playwright/cli@0.1.18
   mkdir -p ~/.local/bin
   ln -sf ~/.local/share/playwright-cli/node_modules/.bin/playwright-cli \
     ~/.local/bin/playwright-cli
   

   Two caveats worth stating to the user rather than burying: ~/.local/bin has to be on PATH or Kiro Crew still reports "not installed" (detection is PATH + the Node bin dirs, nothing else); and NPM_CONFIG_USERCONFIG=/dev/null deliberately ignores their employer's registry configuration, which is their call to make, not ours to assume.

4. Air-gapped: npm pack @playwright/cli on a connected machine, copy the .tgz over, then npm install -g ./playwright-cli-<version>.tgz. Note the tarball alone is not runnable -- it needs its playwright / playwright-core dependencies resolved too.

What does not substitute for it: pip install playwright and dotnet tool install Microsoft.Playwright.CLI install a DIFFERENT tool -- the playwright browser-installer/codegen CLI, not @playwright/cli (binary playwright-cli, its own 0.x line, which depends on playwright@1.63.0-alpha). Switching to yarn, pnpm or bun hits the same registry, so it only helps when the npm client itself is missing. And there is no standalone binary: the upstream GitHub release carries no build assets and playwright-cli.js starts with #!/usr/bin/env node, so Node.js 18+ is required no matter how it is fetched.

Approval: page-scoped verbs run without prompting the user, because installing the CLI is itself the consent. Verbs that reach the local machine still prompt on purpose -- eval, run-code, upload, state-load, a named state-save, and the installers. Let the user approve those rather than rewriting the command to dodge the prompt.

The full verb list is in the skill playwright-cli install --skills agents --global writes.

Autonomous Task Runner

Subagents

Cron Jobs

Learning & Memory

Artifacts

LLM-generated UI components (widgets, HTML, markdown, SVG, JSON, text).

Agents & Workspaces

On the CLI, --dir must resolve to a strict descendant of $KIROCREW_HOME (default ~/.kiro/crew): anything landing outside — /tmp/x, ../x, ~/x — is refused with a SEL denied audit event, and so is the data home root itself (in any spelling: absolute, ~/.kiro/crew, ., or empty), since a workspace there would put agent-writable memory on top of config.json and .env. The test is containment, not "is it absolute": an absolute path landing under the home is accepted, since it resolves where the relative form would. Pass workspace-myproject, not /path/to/dir.

Note the surface difference: the dashboard POST /api/workspaces DOES accept an absolute dir (screened by is_sensitive_path, so ~/.ssh / ~/.aws / keystone paths are still refused). The CLI is the stricter of the two.

Apps

Configuration

Profiling (debug-only)

Off unless KIROCREW_DEBUG=1 is set; the CLI is the only entry point. Emits folded stacks (open in speedscope / flamegraph.pl). See docs/architecture/design-notes/profiling.md.

On macOS the attach path additionally needs elevated privileges (the OS denies task_for_pid), so it may require sudo; --call needs neither py-spy nor sudo.

desktop metrics reads a recording rather than querying the app: getAppMetrics() is Electron-main-only, so the app samples itself into an artifact when started with KIROCREW_DEBUG set. Setting the variable only for the CLI does not make an already-running app record -- restart it.

Security & Eval

Governance Policy

Inspects the two-level security model (effective = POLICY ∩ PROFILE, tightest-wins). Six verbs: five are read-only, and fetch writes — it applies the central policy when the download is usable. The enterprise ceiling is never hand-edited through the CLI (its files are keystone-fenced so the agent cannot read or write them).

Cloud (Bring-Your-Own AWS)

Runs Kiro Crew on an EC2 instance in your own AWS account; credentials are resolved by the aws CLI and never stored by Kiro Crew. All verbs accept --profile / --region; the single-instance verbs also accept --tag (defaults to the last launched instance).

Tailnet (Tailscale)

Publishes this dashboard on your tailnet and trusts its origin, so a device on the tailnet reaches it without a public tunnel.

up publishes only a port it has evidence for: an explicit --port, KIROCREW_PORT, or the running gateway's run marker. With none of those — the gateway is down, the marker is unreadable, or several gateways are up, where the marker deliberately refuses — up refuses rather than falling back to the configured dashboard.url port, because nothing is verified to answer there and tailscale serve would expose whatever does. Start the gateway and re-run, or name the port yourself. status and down do accept the configured port: one only reports, and the other checks mount ownership before removing anything.

Computer Use (Desktop Automation)

Default-OFF behind a keystone enable (~/.kiro/crew/computer_use.json, not config.json). macOS and Windows carry the full tool set; Linux answers a typed unsupported refusal. On Windows there is no per-process input, so a keystroke takes the user's keyboard focus and a coordinate click moves their real cursor — say so rather than reporting a silent success. These are human debug/diagnostic twins of the computer_* MCP tools — the agent uses the MCP tools, not these.

Snapshot & Restore

Slack Commands

All Allowed Users

Owner-Only Slash Commands

Environment Variables