# Install from GitHub to Codexnpx skills add https://github.com/codemix/cli --skill codemix-cli -a codex# Install from a local codemix/cli checkout (run from repo root)npx skills add . --skill codemix-cli -a codex
Use -g to install globally (available across projects):
npx skills add https://github.com/codemix/cli --skill codemix-cli -a codex -g
Command map
Top-level commands:
codemix login
codemix logout
codemix whoami
codemix init
codemix ask
codemix discover
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.
Also ensures .codemix/ is present in .gitignore.
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)
--api-key <key> use this API key for this command only
--ai <tool> local AI tool (claude, cursor-agent, or codex; aliases: cursor, agent, codex-cli); required in non-interactive mode. If omitted in interactive mode, you'll be prompted to choose.
--create-proposal create draft proposal from changed markdown upserts
--proposal-title <title> override generated proposal title
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 and ensures .codemix/ is ignored in .gitignore:
{ // JSON Schema for editor IntelliSense and validation "$schema": "https://unpkg.com/codemix/codemix.schema.json", // 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
npm run typechecknpm run testnpm run pack:checknpm publish --access public
pack:check runs npm pack --dry-run so you can verify the published tarball includes README.md, LICENSE, dist/index.js, codemix.schema.json, SKILL.md, and package.json.