npm package: @iris-point/cogix-cli
Description: Cogix CLI launcher (installs and runs the Rust cogix binary)
Latest version: 0.1.9

# Cogix CLI

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

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

## Install via npm

```powershell
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:

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

## Build

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

Binary:
- `cogix-cli\\target\\release\\cogix.exe`

## Configure

```powershell
./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):

```powershell
./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):

```powershell
./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):

```powershell
./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:

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

`examples/mcp-batch.json` format:

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

List projects:

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

Create an experiment:

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

List MCP tools:

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

Generic API fallback for full backend coverage:

```powershell
# 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:

```powershell
./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

```powershell
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:

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

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