CLI

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:

npm install -g codemix
codemix --version

Use npx for one-off runs:

npx codemix@latest --help

Authenticate

Use browser login for human work:

codemix login
codemix whoami

Use an API key for automation:

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

Create keys in Settings > API Keys. Do not put personal keys in shared prompts or checked-in config.

Set project context

Most commands need an organization and project.

codemix init --project your-org/your-project

That writes codemix.jsonc:

{
  "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.

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.

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

Use it when:

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

You can also create a proposal from the discovered changes:

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

Execute tasks

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

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:

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.

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:

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.