CLI Reference

Kolega.dev CLI

The official command-line interface for the Kolega.dev public API. Use it to authenticate, run scans, triage findings, trigger autofixes, and open pull requests without leaving the terminal.

npm package

@kolegaai/cli

Source code

github.com/kolega-ai/kolega-dev-cli

Related docs

Public API Reference

Overview

The CLI exposes the same public API capabilities that are documented in the web reference, but optimized for terminal workflows and automation. It supports device-flow login, API-key auth, scan execution, finding review, AI fix generation, pull request creation, and quota inspection.

It is published on npm as @kolegaai/cli and installs a kolega binary.

Install

Install the CLI globally from npm. The published package requires Node.js 22 or newer.

npm install -g @kolegaai/cli

Quick Start

A typical first session is: authenticate, list applications, start a scan, then check remaining quota. The CLI supports default as the application id when your organization has only one application.

# Authenticate (opens browser for device-flow pairing)
kolega auth login

# List your applications
kolega apps list

# Run a secrets scan and wait for results
kolega scans start default --type secrets --wait

# See what's left in your quota
kolega quota

Authentication

Device flow is the recommended interactive login method. For CI or headless automation, use an API token directly with --token or KOLEGA_TOKEN.

kolega auth login

kolega auth login --token kcp_live_...

export KOLEGA_TOKEN=kcp_live_...

Stored credentials live at ~/.config/kolega/config.json with file mode 0600.
kolega auth status shows the redacted token source and current period information.
kolega auth logout removes the stored credential.

Command Groups

Commands are organized around the same resource groups as the public API: applications, scans, findings, fixes, and quota.

Applications

Inspect the applications available to the authenticated organization.

kolega apps list [--include-archived]
kolega apps get <application-id>

Most commands accept `default` as the application id when the organization has only one application.

Scans

Trigger security scans, inspect scan batches, and tail progress from the terminal.

kolega scans list <app-id> [--scan-type <type>] [--status <status>]
kolega scans start <app-id> --type <secrets|semgrep|deep-ai> [--wait]
kolega scans get <app-id> <scan-id>
kolega scans progress <app-id> <scan-id> [--watch] [--interval <sec>]
kolega scans results <app-id> <scan-id>

`--wait` streams progress until the scan reaches a terminal state.
`--no-quota-check` skips the pre-flight quota validation.

Findings

List findings, inspect a single finding, or update its lifecycle status.

kolega findings list <app-id> [--severity <severity>] [--status <status>] [--scan-batch-id <id>]
kolega findings get <app-id> <finding-id>
kolega findings set-status <app-id> <finding-id> [status]

Omitting the status argument triggers an interactive prompt.
Valid statuses include `open`, `resolved`, `ignored`, `false_positive`, and `needs_manual_review`.

Fixes

Create AI remediation runs, watch progress, inspect diffs, and open pull requests.

kolega fixes run <app-id> --finding-ids <id,id> --instructions "..." [--wait]
kolega fixes list <app-id> [--finding-id <id>]
kolega fixes get <app-id> <fix-id>
kolega fixes progress <app-id> <fix-id> [--watch]
kolega fixes diff <app-id> <fix-id>
kolega fixes pr <app-id> <fix-id> [--title <title>] [--body <body>] [--branch-name <name>]

If `--instructions` is omitted, the CLI opens `$EDITOR` for multi-line instructions.
If `--source-repo` is omitted, the CLI auto-picks the application's only repo or prompts you to choose.

Quota

Check current-period balances for scans, PRs, and application slots.

kolega quota

Automation & JSON

Every command supports --json, which emits the raw API response shape for scripting and CI pipelines.

# Get the first application ID
kolega apps list --json | jq -r '.items[0].id'

# Count high-severity findings
kolega findings list default --severity high --json | jq '.total'

# Pipe a diff to a file
kolega fixes diff default <fix-id> --json | jq -r '.diff' > fix.patch

Global flags and environment variables

Flag	Env var	Description
--api-url <url>	KOLEGA_API_URL	Override the default API base URL (`https://api.kolega.dev`).
--json	-	Emit raw JSON for scripting instead of formatted terminal output.
-	KOLEGA_TOKEN	Provide an API token directly; it takes precedence over stored config.
-	NO_COLOR	Disable colored CLI output.

Exit codes

Code	Meaning
0	Success
1	Generic error
2	User interrupted (Ctrl+C)
3	Quota exhausted
4	Not authenticated
5	API error

Development

The CLI repo includes generated OpenAPI types, a Commander-based entry point, per-resource command modules, and a thin API client around the public API. Use the GitHub repo for source and issue tracking.

git clone https://github.com/kolega-ai/kolega-dev-cli
cd kolega-dev-cli
npm install
npm run generate-types
npm run build
npm test
npm run lint

npm run generate-types fetches the OpenAPI schema and regenerates TypeScript types.
The CLI entry point is implemented in src/cli.ts in the CLI repo.
Resource command groups live under src/commands/ in the CLI repo.