kelocan

CLI for the Kelocan kanban board — a thin client over the REST API, designed for humans and AI agents (low-token output via --json / --fields).

Install

npm install -g kelocan        # or: npx kelocan <command>

Requires Node.js ≥ 20.

Onboarding — install the MCP server & skills into your agent

npx kelocan init

One command: logs you in (browser), detects installed agents, lets you pick which to configure, writes the kelocan MCP entry and the agent skills, then verifies the connection — in ≤ 3 prompts.

Supported agents:

| Agent | Config file | Entry | Auth | Skills dir | | --- | --- | --- | --- | --- | | Devin CLI | ~/.config/devin/mcp_config.json | mcpServers.kelocan.url | OAuth | ~/.agents/skills | | Claude Code | claude mcp add (fallback ~/.claude.json) | mcpServers.kelocan (http) | OAuth | ~/.claude/skills | | Cursor | ~/.cursor/mcp.json | mcpServers.kelocan.url | OAuth | ~/.agents/skills | | Codex | ~/.codex/config.toml | [mcp_servers.kelocan] + bearer_token_env_var | API key env | ~/.agents/skills | | Opencode | ~/.config/opencode/opencode.json | mcp.kelocan (remote) | OAuth | ~/.agents/skills | | Antigravity | ~/.gemini/antigravity/mcp_config.json or ~/.gemini/config/mcp_config.json (whichever exists) | mcpServers.kelocan.serverUrl + headers | API key header | skills/ next to the config | | Hermes | ~/.hermes/config.yaml | mcp_servers.kelocan + auth: oauth | OAuth | ~/.hermes/skills |

Safety: only the kelocan entry is ever merged — other MCP entries are left untouched, the original file is backed up to <config>.bak, and re-running is idempotent. Secrets are never written literally; API-key installs reference $KELOCAN_API_KEY from the environment.

Non-interactive:

kelocan init --agent devin,cursor        # specific agents
kelocan mcp install --agent all          # only MCP entries
kelocan skills install --agent claude    # only skill files
kelocan uninstall --agent codex          # remove kelocan entry + skills only
kelocan doctor                           # verify everything (read-only)

The skills can also be installed by any agent that supports the Agent Skills convention: npx skills add IFLyer/kelocan-cli.

Auth

kelocan login                          # browser flow: opens the /cli/authorize page
kelocan login --api-key klc_...        # headless: store an existing API key
kelocan login --url http://localhost:8001 --web-url http://localhost:5173
kelocan whoami
kelocan logout

Config is stored in ~/.config/kelocan/config.json (mode 600; %APPDATA%/kelocan on Windows). Environment overrides: KELOCAN_URL, KELOCAN_API_KEY, KELOCAN_WEB_URL.

Commands

| Command | Description | | --- | --- | | board show <board> | Board columns & task counts | | task list <board> [--column X] [--label Y] [--sprint Z] | List tasks | | task show <id> | Task detail | | task prompt <id> | Rendered agent prompt | | task create <board> --title "..." [--column X] [--kind task\|idea\|feedback] [--priority low\|medium\|high\|urgent] [--label a,b] [--sprint active\|backlog\|uuid] | Create task | | task move <id> --to <column\|role> [--position N] | Move task | | task comment <id> -m "..." / --file path | Add comment / attachment | | run start <task> --agent "Devin" | Open agent run (prints run_id) | | run finish <run_id> --outcome succeeded\|failed\|cancelled -m "..." | Close run | | subtask list <task> / subtask toggle <id> | Sub-task checklist |

Boards, columns, and labels can be referenced by name, workflow role (backlog|active|review|done) or UUID. Ambiguous names produce an error listing the candidates.

Output & exit codes

Default output is concise text. --json prints the raw API payload; --fields a,b,c selects fields (JSON objects, or tab-separated text).

Exit codes: 0 success · 1 validation/usage (message lists valid values) · 2 auth · 3 network/server.

Every command supports --help with examples: kelocan task create --help.

Agent workflow example

kelocan task prompt 8c8fb91c-... > prompt.md          # fetch instructions
kelocan run start 8c8fb91c-... --agent "Devin"        # -> run_id: ...
kelocan task comment 8c8fb91c-... -m "Progress: ..."  # report progress
kelocan task move 8c8fb91c-... --to review            # move card
kelocan run finish <run_id> --outcome succeeded -m "PR opened"

Development

npm install
npm run build          # tsc -> dist/
npm test               # unit tests (node:test via tsx)
npm run test:e2e       # e2e vs live backend (needs KELOCAN_E2E=1, KELOCAN_URL, KELOCAN_API_KEY)

Publishing

GitHub Actions publishes to npm when a v* tag is pushed (.github/workflows/publish.yml). Requires an NPM_TOKEN secret.