kura-agent-cli

Command-line interface for Kura. Two surfaces:

1. kura agent ... — submit AI-built sites to Kura's agent-import endpoints (customer-facing).
2. kura pull / push / status / abort / extend / serve — local Claude Code editing for Kura-managed sites (admin-only).

Install

npm install -g kura-agent-cli

Auth

Mint an API key:

• Customers: www.kurawebsites.com/account/api-keys (scope: agent-import)
• Admins: www.kurawebsites.com/admin/settings/api-keys (scope: admin-full)

Then either:

export KURA_API_KEY=kura_<your-48-hex-key>

Or create ~/.kurarc:

{ "api_key": "kura_<your-48-hex-key>" }

Agent-import usage (customer-facing)

From the root of your agent-built site directory (the one containing kura.config.json):

kura agent validate .                        # dry-run — no side effects
kura agent submit .                          # first build, AND every update to a live site
kura agent approve . <approvalId> --yes      # after the owner said yes in chat
kura agent approve . <approvalId> --code C   # an approval that needs the owner's emailed code
kura agent withdraw . <approvalId>           # the owner said no
kura agent status <projectId>                # check build progress

The CLI walks the directory, skips node_modules / dist / .env*, and classifies each file as utf-8 text or base64 binary by extension.

• A folder bound to a Kura project (.kura/scaffold.json from kura launch, or .kura/project.json) ships through that project's build surface, /api/agent/me/build/* (ADR 0290). The server backs a draft or redeploys the live site, and a live rebuild parks until the owner says yes. The CLI uses its own key for the project: minted once from your account key via POST /api/agent/mint-project-key and stored only in ~/.kura/project-keys.json (override the path with KURA_PROJECT_KEYS_PATH). Never put a Kura key in the site folder or a .env file.
• A folder with no project POSTs to /api/agent/projects, which creates one.

Every ship/approve command ends with one RESULT: … line (DEPLOYED, PARKED, VALIDATION FAILED, SUBMIT FAILED, BUILD FAILED, STILL BUILDING, APPROVED, WITHDRAWN, CODE SENT, NEEDS OWNER YES, APPROVAL FAILED). Approvals happen in chat with the owner, never in the Kura dashboard.

A submitted or approved build is followed by its own build id (GET /api/agent/me/build/state?buildId=…, agent contract 1.47, ADR 0305), never by "the newest deploy": BUILD FAILED names the reason the deploy recorded (a field-stamp gate refusal such as marker_gate_coverage, a crash as deploy_crashed), and another deploy's outcome (an owner publish) is never reported as this build's. Against a server older than 1.47 the CLI says STILL BUILDING rather than guess.

See the agent integration guide for the full kura.config.json schema and per-framework rules.

Admin usage

For Kura admins managing existing customer projects:

kura pull <project-id|slug>     # fetch pages locally + claim lock
kura status                     # show local changes
kura push [--yes]               # save + publish + release lock
kura abort                      # release lock without writing
kura extend                     # extend lock by 2h
kura serve [--port=4001]        # localhost preview

Requires an admin-full scope key.

Configuration

KURA_API_KEY      — your bearer token (required, kura_<48 hex>)
KURA_BASE_URL     — orchestrator URL (defaults to prod)

Source

This package lives in github.com/benbybee/kura-orchestrator/tree/main/cli. PRs welcome.