Using the CLI

Install and log in to the Kolleague CLI, and manage workspaces, issues, agents, and runtimes from the terminal.

The Kolleague CLI both connects local runtimes and manages workspaces, issues, agents, and automations from the terminal. This page covers the common paths; the flags your installed version supports are always defined by each command's own --help.

Installation

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/KommitAI/kolleague/main/scripts/install.sh | bash

Windows PowerShell

irm https://raw.githubusercontent.com/KommitAI/kolleague/main/scripts/install.ps1 | iex

Confirm the install:

kolleague version

First connection

Connect to Kolleague Cloud:

kolleague setup

setup saves the server address, opens a browser to complete sign-in, and starts the daemon. When it finishes, check:

kolleague auth status
kolleague daemon status

If you only need to sign in again without overwriting other configuration, run kolleague login. On a machine without a browser, create a personal access token in the web settings first, then enter it with:

kolleague login --token

The command prompts you to paste the token in the terminal, keeping the full value out of shell history.

Choosing a workspace

List workspaces and switch the default:

kolleague workspace list
kolleague workspace switch <slug>

Subsequent commands use this workspace. A single command can override it with --workspace-id, or you can set KOLLEAGUE_WORKSPACE_ID.

Invite members:

kolleague workspace member invite teammate@example.com
kolleague workspace member invite admin@example.com --role admin

Common issue operations

# View and search
kolleague issue list
kolleague issue get KOL-123
kolleague issue search "login failure"

# Create and update
kolleague issue create --title "Fix login failure"
kolleague issue status KOL-123 in_progress
kolleague issue assign KOL-123 --to "Backend Agent"

# Comments and runs
kolleague issue comment list KOL-123
kolleague issue comment add KOL-123 --content "Check the regression tests first"
kolleague issue runs KOL-123

Read long descriptions or comments from stdin to avoid dealing with newlines and quoting:

kolleague issue create --title "Upgrade notes" --description-stdin < notes.md
kolleague issue comment add KOL-123 --content-stdin < review.md

View the messages of a single run, or stop a task:

kolleague issue run-messages <task-id> --issue KOL-123
kolleague issue cancel-task <task-id> --issue KOL-123

Agents and skills

kolleague agent list
kolleague agent get <agent-id>
kolleague agent create --help
kolleague agent update <agent-id> --help

kolleague skill list
kolleague skill get <skill-id>
kolleague skill import --url <skill-url>
kolleague agent skills add <agent-id> --skill-ids <skill-id>

When an import hits a skill with the same name, the default is to stop without modifying existing content. Pick by intent:

kolleague skill import --url <skill-url> --on-conflict overwrite
kolleague skill import --url <skill-url> --on-conflict rename
kolleague skill import --url <skill-url> --on-conflict skip

overwrite is only allowed for the skill's creator and preserves the original ID and agent bindings.

Daemon and runtimes

kolleague daemon start
kolleague daemon stop
kolleague daemon restart
kolleague daemon status --output json
kolleague daemon logs --follow

kolleague runtime list
kolleague runtime rename <runtime-id> "Office Mac"
kolleague runtime usage <runtime-id>
kolleague runtime activity <runtime-id>

Deleting a runtime that still has active agents bound to it is refused by default. kolleague runtime delete <id> --cascade unbinds those agents, preserves their configuration and history, and cancels their active tasks.

See Daemon and runtimes for how it works and for custom profiles.

Command overview

Command	Purpose
`issue`	Create, update, assign, and search issues; manage comments, subscribers, labels, properties, and runs
`project`	Manage projects and their resources
`label`, `property`	Manage workspace labels and custom properties
`agent`, `skill`, `squad`	Manage agents, skills, and squads
`autopilot`	Manage automations, triggers, and run history
`workspace`	Create, view, and switch workspaces, and invite members
`repo`	Manage workspace repositories and check them out locally
`daemon`, `runtime`	Start and stop the local daemon; view and manage runtimes
`attachment`	Upload or download attachments
`user profile`	View or update the current user's profile
`auth`, `login`, `setup`	Log in, check auth status, and initialize a connection
`config`	View or edit the current CLI profile's local configuration
`update`, `version`	Update the CLI or print the version

kolleague chat reads the external chat session an agent is currently handling; it is mainly for agents in chat integrations, not a general command for browsing arbitrary workspace conversations.

IDs and output formats

Issues use keys like KOL-123 or full UUIDs; short UUID prefixes are not accepted.

list commands for other resources usually print copyable short IDs and support --full-id for the full UUID. When a short ID is ambiguous, the CLI asks for more characters or the full UUID. Short task IDs also require --issue to identify the owning issue.

Many commands support structured output:

kolleague issue list --output json
kolleague agent list --output json

Scripts should use JSON output rather than parsing the terminal-oriented tables. The output formats and pagination flags each command supports are defined by kolleague <command> --help.

Profiles and configuration

The default configuration lives in ~/.kolleague/config.json. Use --profile <name> to isolate a separate set of server address, token, default workspace, and daemon state:

kolleague setup --profile staging

kolleague issue list --profile staging

Named profiles live in ~/.kolleague/profiles/<name>/config.json. Inspect the current values:

kolleague config show
kolleague config show --profile staging

CLI configuration files contain tokens that can access Kolleague as you. Don't commit them to a repository, upload them to logs, or share them with others.

Command reference

The tables below cover every current top-level command, grouped the way the CLI itself groups them. All commands accept the global flags --server-url, --workspace-id, --profile, and --debug. --output is registered per command, and the default format varies: list commands default to a table, while get and create commands mostly default to JSON. Full flags are defined by kolleague <command> --help.

Core

Command	Subcommand	Purpose	Key flags
`issue`	`list`	List issues	`--status`, `--priority`, `--assignee`, `--project`, `--metadata` (repeatable), `--limit`, `--offset`, `--sort`, `--full-id`
	`get <id>`	Show a single issue
	`create`	Create an issue	`--title` (required), `--description` / `--description-stdin` / `--description-file`, `--status`, `--priority`, `--assignee`, `--parent`, `--stage`, `--project`, `--start-date`, `--due-date`, `--attachment` (repeatable)
	`update <id>`	Update issue fields	Same fields as `create`, plus `--position`
	`assign <id>`	Assign or unassign	`--to` (fuzzy name match against members, agents, and squads), `--to-id`, `--unassign`
	`status <id> <status>`	Change status
	`reorder <id>`	Move within a column
	`search <query>`	Search issues	`--limit`, `--include-closed`
	`children <id>`	List sub-issues grouped by stage
	`pull-requests <id>`	List linked PRs
	`comment list/add/delete/resolve/unresolve`	Manage comments	`add`: `--content` / `--content-stdin` / `--content-file`, `--parent`, `--attachment`; `list`: `--since`, `--thread`, `--tail`
	`subscriber list/add/remove <issue-id>`	Manage subscribers	`--user`, `--user-id` (defaults to the current user)
	`label list/add/remove <issue-id>`	Manage labels on an issue
	`metadata list/get/set/delete <issue-id>`	Manage issue-level key-value metadata
	`property list/set/unset <issue-id>`	Set custom property values	`set`: `--name`, `--value`
	`runs <issue-id>`	View run history	`--full-id`
	`run-messages <task-id>`	View the messages of a single run	`--since`, `--issue`
	`usage <issue-id>`	View aggregated token usage
	`rerun <id>`	Re-enqueue a run for the current assignee
	`cancel-task <task-id>`	Cancel a running or queued task	`--issue`
`project`	`list/get/create/update/delete`	Manage projects
	`status <id> <status>`	Change project status
	`resource list/add/update/remove`	Manage project resources	`--type`, `--url`
`label`	`list/get/create/update/delete`	Manage workspace labels
`property`	`list/get/create/update/archive/unarchive`	Manage workspace custom properties	`create`: `--name`, `--type`, `--option` (repeatable); `list`: `--include-archived`; the type cannot be changed after creation
`agent`	`list/get/create/update/archive/restore`	Manage agents	`--name`, `--runtime-id` (required for `create`), `--instructions`, `--model`, `--thinking-level`, `--mcp-config`, `--permission-mode`, `--max-concurrent-tasks`
	`copy <agent-id>`	Copy into a new agent; the original is untouched	`--name` (defaults to the original name plus `(copy)`), `--runtime-id` (copying to another runtime also requires `--model`), `--no-skills`; secret configuration such as `custom_env`, `mcp_config`, and `runtime_config` is not copied — re-provide it with the same flags as `create`
	`tasks <id>`	View an agent's tasks
	`avatar <id>`	Upload an avatar
	`env get/set <agent-id>`	Read and write custom environment variables (owner and admin only)
	`skills list/set/add <agent-id>`	Manage attached skills	`--skill-ids` (`set` replaces the full list, `add` appends)
`autopilot`	`list/get/create/update/delete`	Manage automations	`create`: `--title`, `--agent`, `--mode` (all required), `--priority`, `--project`, `--subscriber` (repeatable)
	`trigger <id>`	Trigger a run manually
	`runs <id>`	View run history
	`trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	Manage schedule and webhook triggers
`workspace`	`list/get/create/update/switch`	Manage workspaces; `switch` sets the current profile's default workspace
	`member list/invite <email>`	View members, send invites	`invite`: `--role` (member or admin, default member)
`repo`	`list/add/remove/checkout`	Manage workspace repositories and check them out locally	`--url` (repeatable); `checkout`: `--ref`
`skill`	`list/get/create/update/delete`	Manage skills
	`import`	Import a skill from a URL or local file	`--url` / `--file`, `--on-conflict` (`fail`, `overwrite`, `rename`, `skip`; default `fail`)
	`search <query>`	Search skills
	`files list/upsert/delete <skill-id>`	Manage the files inside a skill
`squad`	`list/get/create/update/delete`	Manage squads (`delete` archives)
	`member list/add/set-role/remove`	Manage squad members
	`activity <issue-id> <outcome>`	Record a leader evaluation
`chat`	`history`, `thread [id]`	Read the external chat session an agent is currently handling	`--limit`, `--before`

Runtime

Command	Subcommand	Purpose	Key flags
`daemon`	`start`	Start the local daemon	`--foreground`, `--device-name`, `--runtime-name`, `--poll-interval`, `--heartbeat-interval`, `--agent-timeout` (`0` means no limit), `--max-concurrent-tasks`, `--no-auto-update`; each has a matching `KOLLEAGUE_*` environment variable
	`stop` / `status` / `restart`	Stop, check status, restart (`restart` takes the same flags as `start`)
	`logs`	View daemon logs	`--follow`, `--lines`
	`disk-usage`	View local disk usage	`--by-workspace`, `--by-task`, `--top`
`runtime`	`list/usage/activity/update/rename/delete`	View and manage runtimes	`delete`: `--cascade` (unbinds bound agents, preserves their data, and cancels their tasks)
	`profile list/create/update/delete`	Manage custom runtime profiles
	`profile set-path/unset-path <profile-id>`	Pin a local executable path (local only, never uploaded to the server)

Additional

Command	Subcommand	Purpose	Key flags
`auth`	`status` / `logout`	Check auth status; `logout` only deletes the locally saved token and does not revoke it on the server
`user`	`profile get/update`	View or update the current user's profile
`login`	—	Sign in via the browser and configure all workspaces automatically	`--token` (prompts interactively in the terminal when passed without a value)
`setup`	`cloud` (default)	Connect to Kolleague Cloud, complete sign-in, and start the daemon
`attachment`	`download <attachment-id>`, `upload <path>`	Download or upload attachments	`download`: `--output-dir`; `upload`: `--task`
`config`	`show`, `set <key> <value>`	View or edit the current profile's local configuration	Precedence: command-line flags > environment variables > `config.json` > built-in defaults; set an empty string to clear a value
`update`	—	Update the CLI to the latest version
`version`	—	Print version information	`--output` (`text` or `json`)

Next steps

Authentication and tokens — creating, renewing, and revoking PATs.
Troubleshooting — diagnosing command errors and tasks that never start.
Create and configure an agent — the full semantics of every agent create field.

On this page