CLI

The CLI calls your Kitecraft API using KITECRAFT_API_URL and KITECRAFT_API_KEY. It prints JSON to stdout. To connect an agent, copy the setup prompt on the documentation home.

Resume onboarding with your agent

kitecraft onboarding status --json
kitecraft onboarding advance --step connections --json

Status reports the same current step as /onboarding, without provider calls. Use the existing website/profile, Google/PostHog, question, visibility and plan commands to complete the current operation. Optional stages can be acknowledged with --step connections, questions or visibility; --step plan finishes only after a real saved plan exists. All acknowledgments require a write key. Read-only keys can inspect progress. Checkout and OAuth consent still happen in the customer’s browser.

Order: trial → website → analysis → optional connections → optional questions → optional visibility → opportunities → plan. Confirm the customer’s research scope once and reuse valid authorization; do not run paid research merely to read progress.

Install and setup

The installed executable is kitecraft. Node.js 22.13 or later is required. Install the release tarball:

npm install --global https://kitecraft.ai/downloads/kitecraft-cli-0.1.0.tgz
kitecraft --help

export KITECRAFT_API_URL="https://kitecraft.ai"
export KITECRAFT_API_KEY="paste-a-key-from-the-dashboard"

For local verification or a supplied preview origin, set KITECRAFT_API_URL to that origin instead, such as http://127.0.0.1:3100. Replace the placeholder with a real key and never commit it. Set the API origin explicitly. A missing key fails configuration; an empty or invalid key is rejected by the server.

Only HTTPS origins are accepted, except HTTP on localhost for local testing.
Never put keys in arguments, files, or screenshots. Use environment variables only.
Market and Google commands need your account-owned project ID as --id. Use kitecraft context --json to find it.

Market: read stored evidence

Status is free of provider calls:

kitecraft market status --id PROJECT_ID

Returns your saved themes, competitors, report (or null if never fetched), status (idle|queued|running|complete|failed), and message. Poll status after a refresh.

Market: save competitors, themes, or refresh

kitecraft market select --id PROJECT_ID --domains "example-a.com,example-b.com"
kitecraft market themes --id PROJECT_ID --json '{"themes":[{"label":"...","rationale":"...","seeds":["seed1"]}]}'
kitecraft market refresh --id PROJECT_ID

select saves up to three known business domains as context, excluding your own website. Rerun to replace.
themes saves one to three editable themes and makes no provider calls. Rerun to replace.
refresh queues one research run with no automatic paid retries. Poll market status until complete or failed.
All three need write access with an active trial or subscription and return { "accepted": true }.

Questions: suggest, select, and edit

kitecraft question status --id PROJECT_ID
kitecraft question generate --id PROJECT_ID
kitecraft question select --id PROJECT_ID --json '{"selectedIds":["..."],"expectedVersion":null}'

status is free of provider calls and returns candidates, recommendations, selection, and run state.
generate runs one paid suggestion with no automatic retry. Needs a saved business profile and write access.
select, edit, add, and archive take JSON payloads with IDs plus the current selection version or question revision. Stale versions fail instead of overwriting.
All writes need an account-owned project and an active trial or subscription. See Monitor questions.

Visibility: check saved answers

kitecraft visibility status --id PROJECT_ID
kitecraft visibility start --id PROJECT_ID
kitecraft visibility run --id PROJECT_ID --run-id RUN_ID
kitecraft visibility observation --id PROJECT_ID --observation-id OBSERVATION_ID
kitecraft visibility cancel --id PROJECT_ID --run-id RUN_ID

status and run are free of provider calls. run returns per-question progress with counts.
start queues one bounded paid check and returns a run ID immediately. Poll status until terminal; partial runs keep successful answers.
observation reads one saved answer with citations and mention evidence. cancel stops further paid submissions.
Starting checks requires write access, an account-owned project and an active trial or subscription. Cancel requires write access and remains available after trial expiry. See Visibility checks.

Google: status, connect, select, sync

kitecraft google status --id PROJECT_ID
kitecraft google connect --id PROJECT_ID
kitecraft google select --id PROJECT_ID --gsc "sc-domain:example.com" --ga4 properties/123456789
kitecraft google sync --id PROJECT_ID

status makes no Google request.
connect returns { "url": "..." }. Open it in the owner browser and complete Google consent. The CLI cannot grant access.
select needs write access. Use currently accessible IDs only.
sync queues one bounded import and needs an active trial or subscription plus write access. Poll google status.
Disconnect is owner-browser-only and has no CLI command.

Limits

Reads are free of provider calls; refresh/sync queue async work. Writes need an account-owned project and an active trial or subscription.

Daily visibility settings: visibility daily --id PROJECT_ID, visibility pause --id PROJECT_ID, and visibility resume --id PROJECT_ID. Resume moves forward to the next UTC window; it does not buy missed days.

Content plan

plan read --id PROJECT_ID reads the saved plan. plan generate --id PROJECT_ID creates it once from saved evidence. An existing plan is returned unchanged.

plan item, plan cluster, and plan cadence accept --id PROJECT_ID --json PAYLOAD. Every edit includes the current expectedRevision; stale edits return a conflict. These edits make no provider calls. See Content plan and the generated API reference for payload fields.

Briefs: request, poll, and read the full artifact

kitecraft brief request --id PROJECT_ID --json '{"itemId":"ITEM_ID"}'
kitecraft brief status --id PROJECT_ID --operation OPERATION_ID
kitecraft brief read --id PROJECT_ID --item ITEM_ID --format markdown > brief.md
kitecraft brief cancel --id PROJECT_ID --operation OPERATION_ID

request starts paid research for one saved plan item and returns a durable operation ID immediately. Add "refresh":true to the JSON payload for an explicit refresh; ordinary re-reads are free.
status is free. Poll until ready, failed, or canceled; it reports saved phases, never invented percentages.
read is free and returns the identical complete Markdown through --format markdown (stdout carries only the artifact) or JSON with markdownHash. --file PATH saves without overwriting an existing file.
cancel stops queued or running research; completed artifacts stay readable. See Writing briefs.

Next content batch

After reading a saved plan, use kitecraft plan extend --id "$PROJECT_ID" --json '{"expectedRevision":4}', replacing 4 with its current revision. It uses current research and previous coverage, appends at most five useful assignments, and preserves existing edits, dates and packets. This is an authorized research write; use a write key. plan generate remains the first-plan operation.

Interview recordings and transcripts

See Interviews and transcripts for private recording uploads, full transcripts, correction and retry commands. MCP tool descriptions include accepted formats and the CLI/API upload path. brief_read returns current ready materials beside the frozen packet; Markdown-only exports need a separate material_list read.

Limits and activity

All keys and interfaces share account request protection. If throttled, wait for the returned retry time before trying again. Billing-period research allowances are separate. Check Activity and usage for current usage and recent operations, and the API reference for request limits.

CLI

On this page