Croche CLI

The @h1r-ai/croche-cli package provides the croche command. Use it directly in a terminal or through your coding-agent plugin.

Install

Use Node.js 22+ on macOS/Linux. Windows verification pending; login and command examples do not claim Windows support.

The intended public npm installation is:

npm install --global @h1r-ai/croche-cli
croche --help
croche projects --help --json

TODO verify: public npm availability, installation, and the command walkthroughs below against the published CLI. Existing project/config/debug commands are source-verified; the planned login and debug-key commands are called out separately below. No public CLI version is promised here.

Help works without credentials. Use the installed command’s --help before changing a project.

Connect your Studio account

Your coding agent installs the CLI first, with the appropriate permission. Then your only setup is to sign up at Studio, create one developer key (dk_) under Account → CLI keys (under Personal), and run this yourself in any private terminal on the same machine and OS user account as the agent:

croche login

Paste the key into the hidden prompt. Only the user runs login; the coding agent never runs it and never asks for the key in chat. A key is never a command-line argument. Login validates it before storing it and prints the account so you can confirm the intended identity.

Planned login — TODO verify: croche login, croche logout, and the identity output/storage behavior below must be checked against the matching released CLI. Do not assume an older CLI supports them. Windows verification pending.

The planned login stores the credential in the OS user configuration directory: XDG on Linux, ~/Library/Application Support on macOS, or %APPDATA% on Windows. POSIX files have 0600 permissions; Windows requires a user-only ACL. The agent must not read the credential file into its transcript. Non-TTY login can read the key from standard input, never argv; that remains a user-controlled/private automation flow, not something the agent runs to collect your key.

After login, the agent can check identity and list projects:

croche auth whoami --json
croche projects list

auth whoami reports the account and credential source (env or stored), with a prefix only, not the secret. Stored login works across terminals under the same OS account without restarting the agent. A remote/container agent has a separate credential context: do not copy credentials through chat to connect it.

Run croche logout yourself to remove the stored credential. For CI only, a secret manager may supply CROCHE_DEVELOPER_KEY; it takes precedence over stored login and is not removed by logout. Do not export it as an extra onboarding step or print the environment to inspect it.

Never put credentials in URLs, commits, screenshots, or command arguments. Local debugging is separate from account authentication.

Let the agent create the project and SDK debug key

Once you have signed up and completed croche login, the agent handles project setup:

croche projects create --name "My app" --json
croche debug-keys create --project PROJECT_ID

Project creation returns the project ID and public project key. The agent uses that public key in app code; you do not need to copy it from Studio. If the app already has an intended project, use that instead of creating another.

Planned CLI workflow — TODO verify: debug-keys create, debug-keys list, debug-keys revoke, and file-output behavior are pending verification against the matching released CLI. Do not assume an older CLI implements them.

The planned debug-keys create command:

• Writes the cdt_ debug key as CROCHE_DEBUG_KEY in ./.env by default. It does not print the secret; output contains only the key ID/prefix and the file location.
• Accepts --env-file PATH to choose the destination. In a Git repository it adds .env to .gitignore; verify the selected path is ignored, especially a custom path.
• Creates the file with 0600 permissions on supported systems. Windows file protection is still pending verification.
• Refuses to replace an existing different value without --force. Stop and get approval before replacing it; preserve other settings. Do not force or repeatedly create keys just to bypass a conflict.

Before creating the debug key, check that the target env file is not already tracked by Git; an ignore rule does not untrack a file. Do not include secret-file contents in a diff or review.

Load the file directly into the local app process (for Node, node --env-file=.env first-turn.mjs). Do not cat it, echo values, paste it into chat, or put the account developer key in the app. If the release offers --print, that is for a human’s private terminal, not a coding agent.

The planned debug-keys list command lists metadata; debug-keys revoke revokes an identified key. Verify their exact arguments with the released CLI help before use. Revoke only the intended key with authorization; neither belongs in a retry loop.

Project commands

Replace PROJECT_ID with a project ID from croche projects list, not the public project key used by the SDK.

Command	Developer task
croche projects list	List your projects
croche projects create --name "Story companion"	Create a project; review its app-access and limit settings in Studio before using it
croche projects get PROJECT_ID	Inspect project setup
croche projects operations PROJECT_ID --limit 100	Inspect recent request reports
croche projects usage PROJECT_ID --period week	Inspect usage; month and all are also supported periods
croche debug-keys list	Planned: inspect debug-key metadata; verify required arguments with released help
croche debug-keys revoke	Planned: revoke an explicitly selected debug key; verify arguments before use
croche keys server list PROJECT_ID	Inspect backend server-key metadata, not secrets
croche attestation get PROJECT_ID	Inspect app-verification settings

Use Studio for the configuration and approvals that require your interaction.

Edit app config

Set CROCHE_PROJECT to your project ID, or pass --project PROJECT_ID on a config command:

croche config get --project PROJECT_ID -o draft.json
# Edit draft.json, keeping every tool and agent your app needs.
croche config save draft.json --project PROJECT_ID --note "Update instructions"
croche config list --project PROJECT_ID

get reads the draft; save updates the draft, not a production release. If a save reports a conflict, read the draft again and reconcile your changes rather than repeatedly overwriting it. A human reviews the draft cards and diff in Build → AI config → Running config, chooses Release…, and approves by typing the project name. Production installs apply it on the next open after sync. Studio is not the draft editor.

A Studio draft replaces the whole code config and applies on the next open after sync. Every debug key follows drafts by default. Include all tools your app uses. See app config and language before saving.

Debug a running development app

Keep the app open. It must expose a supported development-debugging connection; the CLI cannot attach to an arbitrary app.

croche debug

In an interactive terminal, choose the available app connection. Open the printed viewer link. Keep debugger links private and keep debugging confined to development.

For automation, choose an explicit connection ID:

croche debug runtimes --json
croche debug connect --runtime-id RUNTIME_ID
croche debug status --json
croche debug disconnect --runtime-id RUNTIME_ID

disconnect detaches the viewer without cancelling the app’s active turn. croche debug stop stops the local debugger and discards its captures. Do not stop it if you still need those captures.

JSON output and errors

Use --json for machine-readable output:

• Success: { "ok": true, "data": ... }
• Failure: { "ok": false, "error": { "code": "...", "message": "..." } }, with optional details.

Exit code	Meaning
0	Success
1	Remote request failed
2	Usage or configuration error
3	Authentication or authorization failure
4	Transport failure or timeout

A timeout does not prove that an action did not run. Check the app or project before repeating a state-changing command. If an operation reports human_session_required, complete that step yourself in Studio.