CLI Reference - Konduktor Docs

The Konduktor CLI lets you do anything you can do in the Konduktor UI. It’s meant to be used both by humans who prefer to manage things from the terminal, and coding agents that can execute commands and manage things in Konduktor for you. Giving agents access to Konduktor is actually a great way to create projects, tasks, manage the board, etc.

Install

npm install -g konduktor

Quick start

# Log in
konduktor auth login --server https://konduktor.example.com --username admin --password secret

# Set your default workspace so you don't have to pass -w every time
konduktor workspaces set-default my-repo

# Create and run a task
konduktor tasks create --title "Fix login bug"
konduktor tasks run <task-id>

# View and manage the board
konduktor board --tui

Configuration

The CLI resolves connection details and output format using environment variables, a config file, or built-in defaults.

Variable	Description	Default
`KONDUKTOR_URL`	Server URL	`http://127.0.0.1:8080`
`KONDUKTOR_TOKEN`	Auth token	(set by `auth login`)
`KONDUKTOR_WORKSPACE`	Default workspace	(set by `workspaces set-default`)
`KONDUKTOR_OUTPUT`	Output format: `human`, `json`, or `toon`	`human`

Environment variables take precedence over the config file (~/.konduktor/cli.json). Use toon output for agent usage — it encodes the same structured data as JSON with significantly fewer tokens.

Commands

`auth`

Authenticate against your Konduktor instance.

konduktor auth login                                           # interactive (prompts for server, user, pass)
konduktor auth login --server http://host:8080 \
  --username admin --password secret                           # non-interactive
konduktor auth logout                                          # clear saved credentials

Flag	Description
`--server <url>`	Server URL (defaults to current config)
`--username <username>`	Username
`--password <password>`	Password (required alongside —username for non-interactive)

`status`

Check server health.

konduktor status
konduktor status --json

`metrics`

Show server resource metrics (CPU, memory, disk, active sessions, worktree disk usage).

konduktor metrics
konduktor metrics --json

`workspaces`

A workspace is a git repository that Konduktor operates in. Projects, tasks, scheduled agents, and documents are all scoped to workspaces.

konduktor workspaces list                                      # list all workspaces
konduktor workspaces add org/repo                              # add a GitHub repo (clones it)
konduktor workspaces add org/repo --name my-project            # custom workspace name
konduktor workspaces add --local /path/to/repo                 # add a local repo
konduktor workspaces info -w <workspace>                       # show details + git status + disk usage
konduktor workspaces remove -w <workspace>                     # unregister (does not delete repo)
konduktor workspaces remove -w <workspace> -y                  # skip confirmation
konduktor workspaces connect-github -w <workspace> \
  --installation-id <id> --repo owner/repo                     # link GitHub App
konduktor workspaces set-default <workspace>                   # set default workspace for all commands
konduktor workspaces set-default --unset                       # clear default workspace

`board`

Display the task board — a kanban-style view of all tasks in a workspace.

konduktor board                                                # text board (uses default workspace)
konduktor board -w <workspace>                                 # specify workspace
konduktor board --tui                                          # interactive TUI
konduktor board --include-done                                 # include done column
konduktor board --include-trash                                # include trash column
konduktor board --project <project-id>                         # filter by project
konduktor board --tui --vertical                               # force vertical layout in TUI
konduktor board --tui --horizontal                             # force horizontal layout in TUI

The TUI mode supports keyboard navigation across columns, seeing task info, running tasks, viewing logs for a running session, and more.

`tasks`

Tasks are units of work that Claude Code agents execute.

Listing and viewing

konduktor tasks list                                           # list all tasks
konduktor tasks list -w <workspace>                            # specify workspace
konduktor tasks list --status to_do                            # filter by status
konduktor tasks list --tag backend                             # filter by tag
konduktor tasks list --priority p0                             # filter by priority
konduktor tasks list --limit 20                                # paginate
konduktor tasks list --limit 20 --page 2                       # page 2
konduktor tasks info <task-id>                                 # full details + run history

Creating

konduktor tasks create --title "Fix login bug"
konduktor tasks create \
  --title "Add search" \
  --description "Implement full-text search for tasks" \
  --priority p1 \
  --tag backend --tag search \
  --status to_do \
  --project <project-id> \
  --phase <phase-order>
konduktor tasks create \
  --title "Refactor auth" \
  --description-file spec.md                                   # load description from file

Editing

konduktor tasks edit <task-id> --title "New title"
konduktor tasks edit <task-id> --priority p0
konduktor tasks edit <task-id> --tag new-tag
konduktor tasks edit <task-id> --description-file updated.md
konduktor tasks edit <task-id> --pr-url https://github.com/org/repo/pull/42
konduktor tasks edit <task-id> --project <project-id> --phase <phase-order>

Moving between columns

konduktor tasks move <task-id> to_do
konduktor tasks move <task-id> in_progress
konduktor tasks move <task-id> pr_submitted
konduktor tasks move <task-id> done

Valid statuses: idea, to_do, in_progress, pr_submitted, done, trash

Running

konduktor tasks run <task-id>                                  # spawn agent in new worktree
konduktor tasks run <task-id> --force                          # run even if blocked or already running
konduktor tasks resume <task-id> --prompt "Also add unit tests"  # resume in existing worktree
konduktor tasks fix-conflicts <task-id>                        # resolve merge conflicts
konduktor tasks retry <task-id>                                # retry a failed task
konduktor tasks stop <task-id>                                 # kill running session

Deleting and restoring

konduktor tasks delete <task-id>                               # move to trash
konduktor tasks restore <task-id>                              # restore from trash

`sessions`

Sessions represent individual agent execution runs. A task can have multiple sessions (retries, resumes).

konduktor sessions list                                        # list all sessions
konduktor sessions list --task <task-id>                       # filter by task
konduktor sessions list --status running                       # filter by status (running, completed, failed)
konduktor sessions list --limit 20 --page 2                    # paginate
konduktor sessions info <session-id>                           # details + duration + exit code

Viewing logs

konduktor sessions logs <session-id>                           # dump session logs (raw JSONL)
konduktor sessions logs <session-id> --pretty                  # pretty-printed output
konduktor sessions logs <session-id> --follow                  # live tail via SSE streaming
konduktor sessions logs <session-id> --poll                    # live tail via polling (like tail -f)
konduktor sessions logs <session-id> --tail 50                 # last 50 lines
konduktor sessions logs <session-id> --start 100 --end 200     # line range
konduktor sessions logs <session-id> --format pretty           # explicit format flag

`projects`

Projects group related tasks and organize them into phases.

konduktor projects list                                        # list projects
konduktor projects list --status active                        # filter by status (draft|active|completed|archived)
konduktor projects create \
  --name "Auth Rewrite" \
  --description "Replace auth middleware" \
  --priority p1 \
  --tag security
konduktor projects info <project-id>                           # details + phases
konduktor projects update <project-id> --status completed
konduktor projects update <project-id> --name "New name" --priority p0
konduktor projects delete <project-id>                         # delete (phases must be empty)

Phases

Phases are ordered stages within a project (e.g. “Design”, “Implementation”, “Testing”).

konduktor projects phases list <project-id>
konduktor projects phases create <project-id> \
  --name "Implementation" --description "Build the feature"
konduktor projects phases update <project-id> <phase-order> \
  --name "New name"
konduktor projects phases delete <project-id> <phase-order>
konduktor projects phases reorder <project-id> \
  --phases 3,1,2                                               # reorder by phase order numbers

`docs`

Manage workspace documents. Documents are injected into agent context when running tasks.

konduktor docs list                                            # list documents
konduktor docs get <doc-id>                                    # view document content
konduktor docs create \
  --title "API Guidelines" \
  --content "Always use REST conventions..."
konduktor docs create \
  --title "Style Guide" \
  --file style-guide.md                                        # load content from file
konduktor docs edit <doc-id> --title "New title"
konduktor docs edit <doc-id> --file updated.md
konduktor docs delete <doc-id>

`questions`

Agents can ask questions during task execution. Answer them via the CLI or UI.

konduktor questions list                                       # list questions
konduktor questions list --status pending                      # filter by status
konduktor questions list --task <task-id>                      # filter by task
konduktor questions list --tui                                 # interactive TUI
konduktor questions create \
  --content "Should we use REST or GraphQL?" \
  --task <task-id> \
  --option "REST" --option "GraphQL" \
  --context "Deciding on API style" \
  --priority 2                                                 # 1–5, lower = higher priority
konduktor questions answer <question-id> "Use REST"
konduktor questions dismiss <question-id>
konduktor questions update <question-id> \
  --status incorporated                                        # pending|answered|dismissed|incorporated

`schedule`

Configure scheduled agents that run on cron schedules to review the board, triage tasks, or run custom workflows. Multiple named schedules are supported per workspace.

Listing and viewing

konduktor schedule list                                        # list all schedules in workspace
konduktor schedule info --schedule <ref>                       # show config for a specific schedule
konduktor schedule logs --schedule <ref>                       # list run history
konduktor schedule logs --schedule <ref> --run <run-id>        # view a specific run

Creating

konduktor schedule create \
  --name pr-reviewer \
  --cron "0 */4 * * *" \
  --instructions "Review open PRs and summarize them"
konduktor schedule create \
  --name nightly-triage \
  --instructions-file triage-prompt.md \
  --disable                                                    # create disabled

Updating

konduktor schedule set --schedule <ref> --cron "0 */4 * * *"
konduktor schedule set --schedule <ref> --enable
konduktor schedule set --schedule <ref> --disable
konduktor schedule set --schedule <ref> \
  --instructions "Focus on triaging new issues"
konduktor schedule set --schedule <ref> \
  --instructions-file instructions.md
konduktor schedule set --schedule <ref> --reset-instructions   # reset to default
konduktor schedule set --schedule <ref> --name new-slug        # rename

Running and stopping

konduktor schedule trigger --schedule <ref>                    # trigger immediate run
konduktor schedule stop --schedule <ref>                       # stop running agent
konduktor schedule delete --schedule <ref>                     # archive (soft-delete)

<ref> accepts a schedule UUID or its slug name (e.g. pr-reviewer).

`config`

Manage workspace-level configuration.

konduktor config get                                           # show config
konduktor config set --auto-fix-merge-conflicts true           # auto-resolve merge conflicts
konduktor config set --auto-fix-ci-failures true               # auto-fix CI failures
konduktor config get-prompt                                    # show task agent system prompt
konduktor config set-prompt --prompt "Always write tests first"
konduktor config set-prompt --prompt-file prompt.md            # load from file
konduktor config set-prompt --reset                            # reset to default

`logs`

View server and runner logs for debugging.

konduktor logs server                                          # recent server logs (last 50 lines)
konduktor logs server --limit 100                              # more entries
konduktor logs server --more                                   # double the default limit
konduktor logs server --json                                   # raw JSON output
konduktor logs runners                                         # runner logs overview (all workspaces)
konduktor logs runner                                          # runner logs for default workspace
konduktor logs runner -w <workspace>                           # runner logs for a specific workspace
konduktor logs runner -w <workspace> --status failed           # filter by status
konduktor logs runner -w <workspace> --limit 10 --offset 10    # paginate

Output format

Most commands accept --json, --human-readable, and --toon flags to override the format for a single invocation. To change the default persistently:

konduktor set-output human   # human-readable tables (default)
konduktor set-output json    # machine-readable JSON
konduktor set-output toon    # compact token-saving format for agents

Global options

konduktor --version          # print version and exit
konduktor --help             # show help text
konduktor help <command>     # show help for a command

Task ID shorthand

Most commands accept task IDs as short prefixes. You don’t need to type the full UUID — the first 8 characters are usually enough:

konduktor tasks info 4d9d444d    # instead of the full UUID

If a prefix is ambiguous, the CLI will tell you to provide more characters.

Agent & CI/CD usage

CI/CD

Set KONDUKTOR_URL and KONDUKTOR_TOKEN as environment variables — no konduktor auth login needed:

# GitHub Actions
env:
  KONDUKTOR_URL: ${{ secrets.KONDUKTOR_URL }}
  KONDUKTOR_TOKEN: ${{ secrets.KONDUKTOR_TOKEN }}
  KONDUKTOR_WORKSPACE: my-repo
steps:
  - run: |
      konduktor tasks create \
        --title "Deploy ${{ github.sha }}" \
        --status to_do

AI agents

The CLI is designed to be used by AI agents as a subprocess. Use toon output format to minimise token usage:

export KONDUKTOR_OUTPUT=toon

konduktor tasks list
konduktor board
konduktor questions list --status pending

The toon format is a compact, token-efficient encoding that conveys the same structured data as JSON with significantly fewer tokens.

Documentation Index

​Install

​Quick start

​Configuration

​Commands

​auth

​status

​metrics

​workspaces

​board

​tasks

​Listing and viewing

​Creating

​Editing

​Moving between columns

​Running

​Deleting and restoring

​sessions

​Viewing logs

​projects

​Phases

​docs

​questions

​schedule

​Listing and viewing

​Creating

​Updating

​Running and stopping

​config

​logs

​Output format

​Global options

​Task ID shorthand

​Agent & CI/CD usage

​CI/CD

​AI agents

Install

Quick start

Configuration

Commands

`auth`

`status`

`metrics`

`workspaces`

`board`

`tasks`

Listing and viewing

Creating

Editing

Moving between columns

Running

Deleting and restoring

`sessions`

Viewing logs

`projects`

Phases

`docs`

`questions`

`schedule`

Listing and viewing

Creating

Updating

Running and stopping

`config`

`logs`

Output format

Global options

Task ID shorthand

Agent & CI/CD usage

CI/CD

AI agents