CLI Reference

Kolega DevSec CLI

The official command-line interface for the Kolega DevSec 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 repositories, start a scan, then check remaining quota. The CLI supports default as the repository id when your organization has only one repository.

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

# List your repositories
kolega repos 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 organization, API key name and scopes, 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: authentication, repositories, scans, findings, fixes, and quota.

Authentication

Pair the CLI with your organization, inspect the active key, and sign out.

kolega auth login [--token <token>]
kolega auth status
kolega auth logout

`kolega auth login` runs the browser device flow; pass `--token` (or set `KOLEGA_TOKEN`) for non-interactive use.
`kolega auth status` shows the organization, API key name and scopes, token source, and quota period.

Repositories

Inspect the repositories available to the authenticated organization.

kolega repos list [--include-archived]
kolega repos get <repository-id>

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

Scans

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

kolega scans list <repo-id> [--scan-type <type>] [--status <status>]
kolega scans start <repo-id> --type <secrets|semgrep|deep-ai|sbom> [--wait]
kolega scans get <repo-id> <scan-id>
kolega scans progress <repo-id> <scan-id> [--watch] [--interval <sec>]
kolega scans results <repo-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, update its status, or stream lifecycle events.

kolega findings list <repo-id> [--severity <severity>] [--status <status>] [--scan-batch-id <id>]
kolega findings get <repo-id> <finding-id>
kolega findings set-status <repo-id> <finding-id> [status]
kolega findings events [--repo <id>] [--finding <id>] [--event-type <type>] [--since <iso>] [--until <iso>]

Omitting the status argument triggers an interactive prompt.
Valid statuses include `open`, `resolved`, `ignored`, `false_positive`, and `needs_manual_review`.
`kolega findings events` is organization-scoped (newest first) — useful for audit trails and polling.

Fixes

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

kolega fixes run <repo-id> --finding-ids <id,id> --instructions "..." [--wait]
kolega fixes list <repo-id> [--finding-id <id>]
kolega fixes get <repo-id> <fix-id>
kolega fixes progress <repo-id> <fix-id> [--watch]
kolega fixes diff <repo-id> <fix-id>
kolega fixes refine <repo-id> <fix-id> --instructions "..." [--wait]
kolega fixes cancel <repo-id> <fix-id>
kolega fixes pr <repo-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 repository's only source repo or prompts you to choose.
`refine` re-runs the agent with follow-up instructions; `cancel` stops a pending or running fix.

Quota

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

kolega quota

Automation & JSON

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

# Get the first repository ID
kolega repos 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.