---
title: Croche CLI
description: Install the CLI, inspect your project, edit app config, and debug an attached development app.
---

[!nav:main](/nav/main.md)

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

## 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:

```sh
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](https://studio.croche.ai), 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:

```sh
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:

```sh
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:

```sh
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](studio.md) 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:

```sh
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](concepts/config.md) 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.

```sh
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:

```sh
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.