# CLI

Use the codemix CLI for project-scoped questions, local discovery, task execution and automation.

The CLI is the fastest way to bring codemix into a development loop.

Use it when you are already in a terminal, when another agent needs a prompt, or when CI needs stable command output.

## Install

Install globally if you use codemix often:

```bash
npm install -g codemix
codemix --version
```

Use `npx` for one-off runs:

```bash
npx codemix@latest --help
```

## Authenticate

Use browser login for human work:

```bash
codemix login
codemix whoami
```

Use an API key for automation:

```bash
CODEMIX_API_KEY=cmx_... codemix --non-interactive whoami --json
```

Create keys in [Settings > API Keys](/content/settings/api-keys/index.html). Do not put personal keys in shared prompts or checked-in config.

## Set project context

Most commands need an organization and project.

```bash
codemix init --project your-org/your-project
```

That writes `codemix.jsonc`:

```json
{
  "project": "acme/billing",
  "apiUrl": "https://codemix.com"
}
```

The CLI uses that file unless you pass `--project` or set `CODEMIX_PROJECT`.

## Ask grounded questions

`codemix ask` queries the project model.

```bash
codemix ask "What rules govern trial expiration?"
codemix ask "Which screens create or update subscriptions?"
codemix ask "What should happen when invoice payment fails?"
```

Good prompts are concrete. Ask about one rule, flow, edge case or decision at a time.

If the answer looks generic, check the project context and discovery coverage before trusting it.

## Run local discovery

Local discovery lets a local coding agent inspect the repository and write discovery artifacts.

```bash
codemix discover --ai=codex
codemix discover --ai=claude
codemix discover --ai=cursor-agent
```

Use it when:

1. hosted discovery is not available on your plan
2. you want to inspect generated markdown before publishing it
3. the repository needs local-only context or tooling

You can also create a proposal from the discovered changes:

```bash
codemix discover --ai=codex --create-proposal
```

## Execute tasks

Once a proposal has published tasks, the CLI becomes the implementation loop.

```bash
codemix task next
codemix task show
codemix task prompt
echo "Implemented and verified the task." | codemix task complete
```

Use `task prompt` when another agent runtime needs the execution prompt without the interactive UI.

If you cannot continue, release or fail the task explicitly:

```bash
codemix task unclaim
codemix task fail --reason "Blocked by missing Stripe test account"
```

Half-owned tasks make parallel work worse. Be boring and explicit.

## Automation mode

Use `--non-interactive` and `--json` for scripts.

```bash
codemix --non-interactive task next --no-prompt --json
codemix --non-interactive task prompt --json
echo "Implemented and ran tests" | codemix --non-interactive task complete --json
```

Common automation variables:

```text
CODEMIX_API_KEY
CODEMIX_PROJECT
CODEMIX_API_URL
CODEMIX_BASE_URL
```

## CLI vs API vs MCP

Use the CLI for shell workflows, local discovery and task lifecycle commands.

Use the API when you are building your own automation around codemix objects and credentials.

Use MCP when an AI client should call codemix as a tool inside its own workflow.