Cogix CLI

Rust CLI for the Cogix platform (projects, experiments, and MCP tools).

Default target is production (https://api.cogix.app).

Install via npm

npm i -g @iris-point/cogix-cli
cogix --help

Notes:

• Windows (win32-x64) includes a bundled cogix.exe in the npm package.
• Other platforms use the launcher path and download matching binaries from GitHub Releases.
• Override download base URL if needed: COGIX_CLI_DOWNLOAD_BASE_URL.
• Override binary path directly: COGIX_CLI_BIN.

One-off invocation without global install:

npx -p @iris-point/cogix-cli cogix --help

Build

cargo build --release --manifest-path .\\cogix-cli\\Cargo.toml

Binary:

• cogix-cli\\target\\release\\cogix.exe

Configure

./cogix-cli/target/release/cogix.exe config path
./cogix-cli/target/release/cogix.exe config set base-url https://api.cogix.app
./cogix-cli/target/release/cogix.exe config set token <BEARER_TOKEN>
./cogix-cli/target/release/cogix.exe config set mcp-key <CGX_MCP_KEY>
./cogix-cli/target/release/cogix.exe config set oauth-client-id <OAUTH_CLIENT_ID>

Env overrides:

• COGIX_BASE_URL
• COGIX_TOKEN
• COGIX_MCP_KEY
• COGIX_CONFIG
• COGIX_OAUTH_CLIENT_ID
• COGIX_CLI_SETUP_URL (defaults to https://cogix.app/cli-setup)
• COGIX_OAUTH_SETUP_URL (legacy alias for setup URL)
• COGIX_CLI_SETUP_AUTOVISIT (1/true/yes/on for non-interactive automation)

Login:

Default (no manual client ID):

./cogix-cli/target/release/cogix.exe login
./cogix-cli/target/release/cogix.exe token
./cogix-cli/target/release/cogix.exe logout

OAuth PKCE (advanced / explicit client flow):

./cogix-cli/target/release/cogix.exe login --no-open --bootstrap-token <BOOTSTRAP_BEARER_TOKEN>
./cogix-cli/target/release/cogix.exe token
./cogix-cli/target/release/cogix.exe logout

Notes:

• login without --client-id / --bootstrap-token uses web setup flow at https://cogix.app/cli-setup.
• The setup page signs you in and redirects back to local CLI callback with a token.
• If you pass --client-id or --bootstrap-token, CLI uses full OAuth PKCE flow against:
  • https://api.cogix.app/api/v1/oauth/.well-known/oauth-authorization-server
• --no-open prints the URL instead of opening a browser.

Examples

API-key-first (agent mode, no user token needed for MCP operations):

./cogix-cli/target/release/cogix.exe mcp keys test
./cogix-cli/target/release/cogix.exe mcp tools list
./cogix-cli/target/release/cogix.exe mcp tools call list_projects --args-json '{}'

Run a full batch with one MCP key:

./cogix-cli/target/release/cogix.exe mcp batch .\examples\mcp-batch.json --continue-on-error

examples/mcp-batch.json format:

[
  { "name": "list_projects", "arguments": {} },
  { "name": "list_experiments", "arguments": { "project_id": "00000000-0000-0000-0000-000000000000" } }
]

List projects:

./cogix-cli/target/release/cogix.exe projects list

Create an experiment:

./cogix-cli/target/release/cogix.exe experiments create <project_uuid> "Stroop Task"

List MCP tools:

./cogix-cli/target/release/cogix.exe mcp tools list

Generic API fallback for full backend coverage:

# PATCH endpoint
./cogix-cli/target/release/cogix.exe api patch /api/v1/preferences --json '{"email_notifications":false}'

# Arbitrary method with custom headers and multipart payload
./cogix-cli/target/release/cogix.exe api request POST /api/v1/project-files/upload `
  --header X-Request-Source=cli `
  --form project_id=<project_uuid> `
  --form-file file=.\asset.png

Dedicated namespaces currently implemented:

• projects
• experiments
• blocks
• sequences
• stimuli
• participants
• aoi
• project-files
• templates (including template comment operations)
• experiment-templates
• api-keys
• agents
• preferences
• experiment-tokens
• mcp

Examples for the newer namespaces:

./cogix-cli/target/release/cogix.exe templates list --limit 20
./cogix-cli/target/release/cogix.exe experiment-templates marketplace --featured-only true
./cogix-cli/target/release/cogix.exe api-keys create "research-key" --project-id <project_uuid> --permission projects:read
./cogix-cli/target/release/cogix.exe agents start <agent_id> --json '{"mode":"auto"}'
./cogix-cli/target/release/cogix.exe preferences update --json '{"email_notifications":false}'
./cogix-cli/target/release/cogix.exe aoi export-all <project_uuid> --coordinate-system pixels --include-analysis true
./cogix-cli/target/release/cogix.exe project-files metadata-get <project_uuid> "assets/hero image.png"

Test

cargo test --all-targets

Integration tests (tests/e2e_cli.rs) run the real CLI binary and validate:

• OAuth login/logout/token end-to-end.
• Project/experiment resource operations end-to-end after login.
• AOI and project-files CLI flows end-to-end.
• Templates, experiment templates, API keys, agents, and preferences CLI flows end-to-end.

Frontend API coverage audit:

node .\scripts\audit-frontend-api-coverage.mjs > .\frontend-api-coverage.json

See docs/frontend-api-coverage.md for latest coverage summary.