codemix CLI

CLI for Codemix, optimized for both humans and agents.

Install

npm install -g codemix

Or run without global install:

npx codemix@latest --help

Quick start

codemix login
codemix init --project your-org/your-project
codemix ask "What does the onboarding flow do?"

Command map

Top-level commands:

• codemix login
• codemix logout
• codemix whoami
• codemix init
• codemix ask
• codemix task
• codemix help [command]

Global options:

• -V, --version
• --non-interactive disable prompts and interactive flows
• -h, --help

Full command reference

codemix login [options]

Authenticate with Codemix.

Options:

• --api-url <url> override Codemix base URL
• --api-key <key> store an API key directly
• --port <port> local OAuth callback port (default: 8399)
• --no-browser do not open browser automatically
• --json output structured JSON

Notes:

• If CODEMIX_API_KEY is set, login is skipped.
• In non-interactive mode, --api-key (or CODEMIX_API_KEY) is required.

codemix logout [options]

Remove stored credentials.

Options:

• --api-url <url> override Codemix base URL
• --json output structured JSON

Note: if CODEMIX_API_KEY is set, stored credentials are not modified.

codemix whoami [options]

Show current authenticated user.

Options:

• --api-url <url> override Codemix base URL
• --api-key <key> use this API key for this command only
• --json output structured JSON

codemix init [options]

Create or update codemix.jsonc.

Options:

• --project <organization/project> set project identifier
• --api-url <url> persist API URL override in config
• --api-key <key> use this API key for this command only (for interactive org/project selection)
• --json output structured JSON

codemix ask [options] <question...>

Ask Codemix a question about the project.

Options:

• --project <organization/project> override project identifier
• --api-url <url> override Codemix base URL
• --api-key <key> use this API key for this command only
• --no-stream disable SSE streaming and wait for full response
• --json output structured JSON

codemix task [options]

Show task dashboard.

Task-scope options (supported by task and inherited by subcommands):

• --project <organization/project> override project identifier
• --api-url <url> override Codemix base URL
• --api-key <key> use this API key for this command only
• --json output structured JSON

Subcommands:

codemix task list [options]

List tasks.

Options:

• --status <status> filter by status
• --assignee <assignee> filter by assignee

Typical statuses include: ready, running, needs_input, planning, blocked, completed, failed, cancelled.

In interactive terminals, task list prompts you to pick a task and shows full details. In non-interactive mode, it prints a compact table.

codemix task show <id>

Show task details.

codemix task next [options]

Claim next available task and emit markdown prompt.

Options:

• --no-prompt claim only (do not emit prompt)
• --wait poll until a task is available

codemix task claim <id>

Claim a specific task.

codemix task unclaim [id]

Unclaim a task. If id is omitted, uses your currently claimed running task.

codemix task prompt [id]

Emit task description as markdown prompt. If id is omitted, uses your currently claimed running task.

codemix task complete [id]

Complete a task. If id is omitted, uses your currently claimed running task.

You can pipe a completion summary through stdin:

echo "Implemented and verified acceptance criteria." | codemix task complete

codemix task fail <id> --reason <reason>

Fail a task.

Options:

• --reason <reason> required failure reason

codemix task log [id]

Show task event timeline. If id is omitted, uses your currently claimed running task.

Agent/automation usage

For deterministic automation:

• Always pass --non-interactive.
• Prefer --json for machine parsing.
• Provide auth via --api-key or CODEMIX_API_KEY.
• Provide project via --project or CODEMIX_PROJECT.

Example agent loop:

codemix --non-interactive task next --wait | your-agent-command

Claim, work, and complete with summary:

codemix --non-interactive task next --no-prompt
# ...do work...
echo "Implemented change and ran tests" | codemix --non-interactive task complete

Fail with explicit reason:

codemix --non-interactive task fail <task-id> --reason "Blocked by missing API endpoint"

Configuration

codemix init creates codemix.jsonc in your working directory:

{
  // Project identifier in organization/project format
  "project": "acme/todoapp",

  // Optional Codemix API base URL override
  "apiUrl": "https://codemix.com"
}

Resolution order:

• API URL: --api-url -> CODEMIX_API_URL/CODEMIX_BASE_URL -> codemix.jsonc apiUrl -> https://codemix.com
• Project: --project -> CODEMIX_PROJECT -> codemix.jsonc project
• Auth token: --api-key -> CODEMIX_API_KEY -> stored credential from codemix login

Environment variables

• CODEMIX_API_KEY
• CODEMIX_PROJECT
• CODEMIX_API_URL
• CODEMIX_BASE_URL (alias for API URL)

Exit codes

• 0 success
• 1 usage error
• 2 authentication error
• 3 not found
• 4 permission denied
• 5 network or unknown runtime error

Maintainer release flow

npm run typecheck
npm run test
npm run pack:check
npm publish --access public

pack:check runs npm pack --dry-run so you can verify the published tarball only includes README.md, dist/index.js, and package.json.