scriptoriumadmin/veritas-kanban

Fork 0

mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00

Brad Groux 3b07a5cb4f

feat: add first-class Claude Code adapter (#951 )

2026-07-24 01:00:09 -05:00

27 KiB

Raw Blame History

CLI Guide

Comprehensive guide to the vk command-line tool for Veritas Kanban.

📋 Back to README · Features · Changelog

Introduction
Installation
Quick Start
Command Reference
Workflow Commands Deep Dive
Scripting & Automation
Configuration
Tips & Tricks

Introduction

vk is the command-line interface for Veritas Kanban — a local-first task management and AI agent orchestration platform. It lets you manage tasks, track time, coordinate agents, and run your entire project workflow without leaving the terminal.

💡 Philosophy: "Automate everything you do twice."

This principle — championed by Boris Cherny, creator of Claude Code — is at the heart of the v1.4 CLI additions. If you're doing the same multi-step workflow every time you start or finish a task, that workflow should be a single command. That's exactly what vk begin and vk done deliver.

The CLI talks to the Veritas Kanban server over its REST API, so any command you run in the terminal has the same effect as clicking through the web UI or calling the API directly with curl.

Installation

# Clone the repository (if you haven't already)
git clone https://github.com/BradGroux/veritas-kanban.git
cd veritas-kanban

# Install dependencies
pnpm install

# Build shared code and the CLI before linking
pnpm --filter @veritas-kanban/shared build
pnpm --filter @veritas-kanban/cli build

# Link the CLI globally from the CLI package
cd cli
npm link

After linking, the vk command is available globally in your terminal.

vk --help
vk setup

Prerequisite: The Veritas Kanban server must be running for CLI commands to work. Start it with pnpm dev from the repository root.

Quick Start

The complete task lifecycle in three commands:

# 1. Create a task
vk create "Implement OAuth login" --type code --project my-app

# 2. Start working — one command handles everything
vk begin task_20260201_abc123

# 3. Finish up — one command wraps it all
vk done task_20260201_abc123 "Added OAuth2 with Google and GitHub providers"

That's it. vk begin sets the task to in-progress, starts the time tracker, and marks the agent as working. vk done stops the timer, marks the task done, adds a closing comment, and sets the agent to idle. What used to require 6+ API calls now takes 2 commands.

Command Reference

Workflow Commands

Composite commands that orchestrate multiple API calls into a single action.

`vk begin <id>`

Start working on a task. Orchestrates three actions in one command.

vk begin task_20260201_abc123

What it does:

Sets task status to in-progress
Starts the time tracker
Updates agent status to working (auto-fetches task title)

Flags:

Flag	Description
`--json`	Output result as JSON

`vk done <id> "summary"`

Complete a task with a summary. Orchestrates four actions in one command.

vk done task_20260201_abc123 "Added OAuth2 with Google and GitHub providers"

What it does:

Stops the time tracker
Sets task status to done
Adds a comment with the summary text
Updates agent status to idle

Flags:

Flag	Description
`--json`	Output result as JSON

`vk block <id> "reason"`

Block a task with a reason.

vk block task_20260201_abc123 "Waiting on API credentials from client"

What it does:

Sets task status to blocked
Adds a comment with the block reason

Flags:

Flag	Description
`--json`	Output result as JSON

`vk unblock <id>`

Unblock a task and resume work.

vk unblock task_20260201_abc123

What it does:

Sets task status to in-progress
Restarts the time tracker

Flags:

Flag	Description
`--json`	Output result as JSON

Task Commands

Core task management commands.

`vk list`

List tasks with optional filters.

vk list                           # All tasks
vk list --status in-progress      # Filter by status
vk list --type code               # Filter by type
vk list --project my-app          # Filter by project
vk list --status in-progress --type code  # Combine filters
vk list --json                    # JSON output

Aliases: ls

Flags:

Flag	Description
`--status`	Filter by status (todo, in-progress, blocked, done)
`--type`	Filter by task type
`--project`	Filter by project name
`--json`	Output as JSON

`vk show <id>`

Show detailed information for a task.

vk show task_20260201_abc123
vk show abc123                    # Partial ID matching supported
vk show abc123 --json

Flags:

Flag	Description
`--json`	Output as JSON

`vk create <title>`

Create a new task.

vk create "Implement OAuth login"
vk create "Fix button alignment" --type code --priority high --project my-app
vk create "Audit without commits" --commit-policy forbidden

Flags:

Flag	Description
`--type`	Task type (code, research, content, etc.)
`--priority`	Priority level (low, medium, high)
`--project`	Project name
`--commit-policy`	Task commit policy (`forbidden`, `allowed`, `required`)
`--json`	Output as JSON

`vk update <id>`

Update task fields.

vk update abc123 --status review
vk update abc123 --title "New title" --priority high
vk update abc123 --commit-policy required

Flags:

Flag	Description
`--status`	New status
`--title`	New title
`--priority`	New priority
`--type`	New type
`--project`	New project
`--commit-policy`	Task commit policy (`forbidden`, `allowed`, `required`)
`--json`	Output as JSON

Time Tracking

Full time management from the terminal.

`vk time start <id>`

Start the time tracker for a task.

vk time start task_20260201_abc123

`vk time stop <id>`

Stop the time tracker.

vk time stop task_20260201_abc123

`vk time entry <id> <seconds> "description"`

Add a manual time entry.

vk time entry task_20260201_abc123 3600 "Implemented login flow"
vk time entry abc123 1800 "Code review"

Arguments:

Argument	Description
`<id>`	Task ID (supports partial matching)
`<seconds>`	Duration in seconds
`"description"`	Description of the work done

`vk time show <id>`

Display time tracking summary for a task.

vk time show task_20260201_abc123
vk time show abc123 --json

Output includes: total time, whether a timer is currently running, and individual time entries with descriptions.

Flags:

Flag	Description
`--json`	Output as JSON

Comments

Add comments to tasks from the terminal.

`vk comment <id> "text"`

vk comment task_20260201_abc123 "Fixed the race condition in the auth flow"
vk comment abc123 "Completed OAuth integration" --author Veritas

Flags:

Flag	Description
`--author`	Author name (default: CLI user)
`--json`	Output as JSON

Agent Status

Manage the global agent status indicator.

`vk agent status`

Show the current agent status.

vk agent status
vk agent status --json

`vk agent working <id>`

Set agent status to working on a specific task. Automatically fetches the task title.

vk agent working task_20260201_abc123

`vk agent idle`

Set agent status to idle.

vk agent idle

`vk agent sub-agent <count>`

Set agent status to sub-agent mode with a count of active sub-agents.

vk agent sub-agent 3

Project Management

Manage projects from the terminal.

`vk project list`

List all projects.

vk project list
vk project list --json

`vk project create "name"`

Create a new project.

vk project create "my-app"
vk project create "rubicon" --color "#7c3aed" --description "Main product"

Flags:

Flag	Description
`--color`	Project color (hex)
`--description`	Project description
`--json`	Output as JSON

Agent Commands

Manage AI agents on code tasks.

Command	Description
`vk start <id>`	Start an agent; optionally require runtime capabilities
`vk launch-preview <id>`	Preview effective launch inputs, blockers, and drift
`vk stop <id>`	Stop a run only when its persisted manifest supports stop
`vk agents:pending`	List pending agent requests
`vk agents:status <id>`	Check agent running status
`vk agents:complete <id> -s --attempt-id <id> --manifest-digest <sha256:...>`	Mark the matching agent attempt complete (success)
`vk agents:complete <id> -f --attempt-id <id> --manifest-digest <sha256:...>`	Mark the matching agent attempt complete (failure)

Require one or more capabilities before launch:

vk start TASK-001 --agent codex \
  --require-capability tool.mcp output.structured \
  --commit-policy allowed \
  --json

Preview without dispatching, or compare a new launch with a parent attempt:

vk launch-preview TASK-001 --agent codex --parent-attempt attempt_parent --json
vk start TASK-001 --agent codex --parent-attempt attempt_parent

Preview output includes the immutable run-launch digest, redacted command and argument plan, per-field origins, enforcement blockers, and material drift. It applies the same readiness gate and override rules as start. Attempt IDs and probe timestamps do not count as material drift.

--require-capability <capabilities...> is additive to the baseline launch, profile, sandbox, and budget requirements. The server returns a structured conflict and the CLI exits non-zero when any capability is unsupported, unknown, missing, or backed by an invalid/failed manifest.

--commit-policy <forbidden|allowed|required> sets the policy for this run. It overrides a task default and the legacy auto-commit setting. Omitting the flag keeps existing tasks compatible: commits are allowed but not required unless a task or legacy setting explicitly requires one.

Use vk agents:status TASK-001 --json to inspect the persisted manifest and capability-derived controls set. vk stop does not infer support from the agent name. It resolves the current attemptId from status and includes it in the stop request, so a replacement run fails a delayed stop closed. The CLI preserves the server's reason when run.stop is unavailable or the active and persisted manifest digests do not match.

Prompt Commands

Sync file-based prompt templates into the runtime prompt registry.

vk prompts import prompt-registry --dry-run
vk prompts import prompt-registry
vk prompts import prompt-registry --force --json

vk prompts import scans Markdown files, skips README.md by default, derives stable IDs from frontmatter id values or filenames, and reports created, updated, unchanged, conflicting, and malformed templates. Runtime templates that differ from disk are conflicts unless --force is passed.

Automation Commands

Manage automation tasks.

Command	Alias	Description
`vk automation:pending`	`ap`	List pending automation tasks
`vk automation:running`	`ar`	List running automation tasks
`vk automation:start <id>`	`as`	Start an automation task
`vk automation:complete <id>`	`ac`	Mark automation complete or failed

Scheduler Commands

Inspect and control recurring work from the terminal.

Command	Description
`vk scheduler list`	List recurring scheduler items and recent events
`vk scheduler run-due`	Run all due scheduler items
`vk scheduler run <id>`	Run one scheduler item now
`vk scheduler pause <id>`	Pause one scheduler item
`vk scheduler resume <id>`	Resume one scheduler item
`vk scheduler validate <id>`	Validate one scheduler item

Item IDs include a source prefix: scheduled-deliverable:<id>, workflow:<id>, or queue-monitor:<id>.

Queue Monitor Commands

Inspect and run policy-gated GitHub queue intake monitors.

Command	Description
`vk queue-monitors list`	List queue monitors, health, and recent events
`vk queue-monitors run <id>`	Run one monitor now
`vk queue-monitors explain <id>`	Build a fresh candidate packet without mutation
`vk queue-monitors health <id>`	Show monitor health and action item state
`vk queue-monitors pause <id>`	Pause one monitor
`vk queue-monitors resume <id>`	Resume one monitor

Every queue monitor command supports --json. run requires workflow:execute; list, health, and explain require workflow:read.

SQLite Journal Maintenance

Preview and schedule safe journal-mode conversion for the configured authoritative database.

Command	Permission	Description
`vk sqlite journal preview --target <mode>`	`backup:write`	Show filesystem, sidecars, ownership, backup, risks
`vk sqlite journal apply ...`	`admin:manage`	Schedule the confirmed preview for the next restart
`vk sqlite journal status [operationId]`	`backup:read`	Show operation and policy state
`vk sqlite journal override revoke --reason`	`admin:manage`	Revoke active compatibility/override policy

apply requires --preview-id, the one-time --preview-token, a matching --confirm, and --acknowledge-risks. It does not convert the live database; restart the server once so bootstrap can run before any SQLite connection opens. All commands support --json. delete mode also requires explicit single-host environment posture and bounded override metadata; see Maintenance Center.

GitHub Sync

Manage GitHub Issues bidirectional sync.

Command	Description
`vk github sync`	Trigger a manual GitHub Issues sync
`vk github status`	Show last sync status (timestamp, counts, errors)
`vk github config`	View or update GitHub sync configuration
`vk github mappings`	List issue↔task mappings

Utilities

Command	Description
`vk summary`	Project stats: status counts, project progress, high-priority items
`vk summary standup`	Daily standup summary (`--yesterday`, `--date YYYY-MM-DD`, `--json`, `--text`)
`vk doctor`	Validate API, routing, executable, and harness support readiness (`--json`)
`vk notify <message>`	Create a notification (`--type`, `--title`, `--task` options)
`vk notify:check`	Check for tasks that need notifications
`vk notify:pending`	Get pending notifications formatted for Teams

vk doctor reads the same redacted harness support projection shown in Settings. Enabled degraded or unsupported profiles fail the doctor check; enabled configured profiles warn until their installed build has current certification evidence. Use vk doctor --json for support-safe automation and diagnostics, including redacted readiness reasons, safe probe commands, and remediation.

For Claude Code, doctor reports the bounded version, auth-status, and agent discovery probes, plus separate bare-mode authentication readiness. A successful interactive OAuth status is diagnostic only because Veritas launches Claude Code with --bare; configure an explicit supported environment credential before enabling the profile.

Workflow Commands Deep Dive

The Problem

Before v1.4, starting or finishing a task required multiple separate API calls. A typical agent workflow looked like this:

# Starting a task (3 calls)
curl -X PATCH http://localhost:3001/api/tasks/<id> \
  -H "Content-Type: application/json" \
  -d '{"status":"in-progress"}'

curl -X POST http://localhost:3001/api/tasks/<id>/time/start

curl -X POST http://localhost:3001/api/agent/status \
  -H "Content-Type: application/json" \
  -d '{"status":"working","taskId":"<id>","taskTitle":"Implement OAuth"}'

# ... work happens ...

# Completing a task (4 calls)
curl -X POST http://localhost:3001/api/tasks/<id>/time/stop

curl -X PATCH http://localhost:3001/api/tasks/<id> \
  -H "Content-Type: application/json" \
  -d '{"status":"done"}'

curl -X POST http://localhost:3001/api/tasks/<id>/comments \
  -H "Content-Type: application/json" \
  -d '{"author":"agent","text":"Added OAuth2 with Google and GitHub providers"}'

curl -X POST http://localhost:3001/api/agent/status \
  -H "Content-Type: application/json" \
  -d '{"status":"idle"}'

That's 7 curl commands across the lifecycle — easy to get wrong, tedious to type, and guaranteed to be inconsistent if you're doing it manually.

The Solution

vk begin <id>
# ... work happens ...
vk done <id> "Added OAuth2 with Google and GitHub providers"

Two commands. Same result. Every step is orchestrated in the correct order, every time.

What Each Command Orchestrates

Command	Step 1	Step 2	Step 3	Step 4
`vk begin`	Status → in-progress	Timer → start	Agent → working	—
`vk done`	Timer → stop	Status → done	Comment → added	Agent → idle
`vk block`	Status → blocked	Comment → reason	—	—
`vk unblock`	Status → in-progress	Timer → restart	—	—

Handling Blocked Tasks

Real-world tasks get blocked. The vk block and vk unblock commands handle this gracefully:

# Task hits a blocker
vk block abc123 "Waiting on API credentials from client"

# Blocker resolved — pick up where you left off
vk unblock abc123

The block reason is automatically recorded as a comment on the task, creating an audit trail of why work was paused.

Scripting & Automation

Every command supports --json output for machine consumption, making vk a first-class tool for scripting and automation.

Piping and JSON Processing

# Get all in-progress task IDs
vk list --status in-progress --json | jq -r '.[] | .id'

# Count tasks by status
vk list --json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Get time spent on a task
vk time show abc123 --json | jq '.totalTime'

Agent Automation

Use workflow commands in agent configurations (like AGENTS.md) to standardize task lifecycle management:

# In an agent's task handler
TASK_ID="$1"

# Start work
vk begin "$TASK_ID"

# ... perform the work ...

# Complete with summary
vk done "$TASK_ID" "Completed implementation of feature X"

CI/CD Integration

# Create a task for each deployment
TASK_ID=$(vk create "Deploy v2.1.2 to staging" --type automation --project ops --json | jq -r '.id')

# Track the deployment
vk begin "$TASK_ID"

# ... deployment steps ...

if [ $? -eq 0 ]; then
  vk done "$TASK_ID" "Successfully deployed v2.1.2 to staging"
else
  vk block "$TASK_ID" "Deployment failed — check CI logs"
fi

Batch Operations

# Block all tasks in a project
vk list --project legacy-app --status in-progress --json | \
  jq -r '.[].id' | \
  xargs -I {} vk block {} "Project on hold pending budget approval"

Configuration

The CLI reads configuration from environment variables:

Variable	Default	Description
`VK_API_URL`	`http://localhost:3001`	Veritas Kanban server URL
`VK_API_KEY`	(none)	API key for authentication

Setting the API URL

# Default — local development
export VK_API_URL=http://localhost:3001

# Remote server
export VK_API_URL=https://kanban.example.com

Setting the API Key

# Set your API key for authenticated endpoints
export VK_API_KEY=your-api-key-here

If you're running locally with localhost auth bypass enabled, read commands may work without a key. Write commands need VK_API_KEY unless VERITAS_AUTH_LOCALHOST_ROLE is set to agent or admin. Prefer an agent role key for CLI automation.

For v5, issue dedicated CLI keys instead of sharing the admin key. Routine automation should use an agent role key; read-only dashboards and reporting scripts should use read-only. Reserve the admin key for setup, migration, backup/import, and policy operations.

The CLI preflights protected commands against /api/auth/context before it calls the target endpoint. If VK_API_KEY lacks the mapped permission, the command fails locally without sending the mutating request.

Read/Write Smoke Check

Use this check after linking vk and exporting VK_API_URL/VK_API_KEY. It proves the CLI can both read from and write to the configured VK server.

# Read check
vk list --json | jq 'length'

# Write check, then cleanup
TASK_ID=$(vk create "CLI auth smoke test" \
  --type automation \
  --priority low \
  --description "Temporary task created by CLI auth smoke test." \
  --json | jq -r '.id')
vk show "$TASK_ID" --json | jq -e --arg id "$TASK_ID" '.id == $id'
vk delete "$TASK_ID" --json

Expected result: the read command prints a number, the show command exits 0, and the delete command returns { "deleted": true }. If read succeeds but write fails with 401 or 403, confirm the exported VK_API_KEY matches an agent or admin role key in VERITAS_API_KEYS, then restart the server.

Tips & Tricks

Shell Aliases

Add these to your .bashrc or .zshrc for even faster workflows:

# Quick task lifecycle
alias vkb='vk begin'
alias vkd='vk done'
alias vkl='vk list --status in-progress'

# Common filters
alias vktodo='vk list --status todo'
alias vkblocked='vk list --status blocked'
alias vkdone='vk list --status done'

# Agent status shortcuts
alias vka='vk agent status'
alias vkai='vk agent idle'

Partial ID Matching

You don't need to type the full task ID. vk show and other commands support partial matching:

# Full ID
vk show task_20260201_abc123

# Partial — just the unique suffix
vk show abc123

Quick Standup

Generate your daily standup in one command:

# Today's standup in the terminal
vk summary standup

# Yesterday's standup (for morning standups)
vk summary standup --yesterday

# Pipe to clipboard (macOS)
vk summary standup --text | pbcopy

Combined Create + Begin

Create a task and immediately start working on it:

# Create and capture the ID
TASK_ID=$(vk create "Fix login bug" --type code --project my-app --json | jq -r '.id')

# Start working
vk begin "$TASK_ID"

Monitoring Agent Status

Check what the agent is up to:

# Current agent status
vk agent status

# See all in-progress tasks (what's being worked on)
vk list --status in-progress

Part of Veritas Kanban · Built by Digital Meld

27 KiB Raw Blame History

CLI Guide

Table of Contents

Introduction

Installation

Quick Start

Command Reference

Workflow Commands

vk begin <id>

vk done <id> "summary"

vk block <id> "reason"

vk unblock <id>

Task Commands

vk list

vk show <id>

vk create <title>

vk update <id>

Time Tracking

vk time start <id>

vk time stop <id>

vk time entry <id> <seconds> "description"

vk time show <id>

Comments

vk comment <id> "text"

Agent Status

vk agent status

vk agent working <id>

vk agent idle

vk agent sub-agent <count>

Project Management

vk project list

vk project create "name"

Agent Commands

Prompt Commands

Automation Commands

Scheduler Commands

Queue Monitor Commands

SQLite Journal Maintenance

GitHub Sync

Utilities

Workflow Commands Deep Dive

The Problem

The Solution

What Each Command Orchestrates

Handling Blocked Tasks

Scripting & Automation

Piping and JSON Processing

Agent Automation

CI/CD Integration

Batch Operations

Configuration

Setting the API URL

Setting the API Key

Read/Write Smoke Check

Tips & Tricks

Shell Aliases

Partial ID Matching

Quick Standup

Combined Create + Begin

Monitoring Agent Status

27 KiB

Raw Blame History

`vk begin <id>`

`vk done <id> "summary"`

`vk block <id> "reason"`

`vk unblock <id>`

`vk list`

`vk show <id>`

`vk create <title>`

`vk update <id>`

`vk time start <id>`

`vk time stop <id>`

`vk time entry <id> <seconds> "description"`

`vk time show <id>`

`vk comment <id> "text"`

`vk agent status`

`vk agent working <id>`

`vk agent idle`

`vk agent sub-agent <count>`

`vk project list`

`vk project create "name"`