taskhelm-cli

TaskHelm CLI

TaskHelm CLI is the first public-facing interface for TaskHelm. It is the terminal entrypoint for developers, platform teams, and operators who need to configure a workspace, inspect engine health, create tasks, use route preview, stream run activity, and integrate TaskHelm into local automation or CI workflows.

The CLI is built around a few constraints:

• workspace-aware behavior should feel natural inside a repository
• local project defaults should be explicit and reviewable
• all core workflows must support both human-readable and machine-readable output
• engine failures should return actionable next steps, not just stack traces
• shell and CI usage should not require the web UI

What The CLI Supports Today

• user-level CLI config plus local project config
• automatic workspace discovery from taskhelm.config.json or YAML
• taskhelm init to bootstrap a workspace
• profile inspection and update commands
• policy and model override inspection
• engine status and connectivity checks
• task creation and route preview
• live run watching over the engine SSE stream
• shell-friendly output and structured JSON errors
• stable, machine-readable error categories and exit-code metadata

Command Tree

taskhelm
|-- version
|-- init
|-- doctor
|-- profile
|   `-- set
|-- policies
|-- models
|-- config
|   |-- path
|   |-- show
|   |-- get <key>
|   |-- set <key> <value>
|   `-- init
|-- engine
|   |-- status
|   `-- ping
|-- task
|   |-- create [options] [prompt]
|   |-- route-preview [options] [prompt]
|   `-- watch <runId>
`-- run
    |-- list
    |-- get <runId>
    `-- logs <runId>

Config Layers

TaskHelm CLI merges configuration in this order:

1. built-in defaults
2. user CLI config
3. local project config
4. environment overrides
5. command-line flags

User CLI config location:

• Windows: %APPDATA%\\TaskHelm\\config.json
• Other platforms: $XDG_CONFIG_HOME/taskhelm/config.json or ~/.config/taskhelm/config.json

Environment overrides are listed in .env.example.

Local MVP Flow

The first engine and CLI integration path has been validated against a live local taskhelm-engine instance using LocalMockProvider.

• Local MVP Quickstart
• Example Commands
• Example Project Config

Current command-to-endpoint mapping:

• taskhelm engine ping -> GET /health
• taskhelm engine status -> GET /health, GET /version, GET /api/providers/health
• taskhelm task route-preview -> POST /api/routing/simulations
• taskhelm task create -> POST /api/runs
• taskhelm run list -> GET /api/runs
• taskhelm run get -> GET /api/runs/:runId
• taskhelm run logs -> GET /api/runs/:runId/events
• taskhelm task watch -> GET /api/runs/:runId/stream

Local Project Config

The CLI automatically looks upward from the current directory for one of these files:

• taskhelm.config.json
• taskhelm.config.yaml
• taskhelm.config.yml

Supported project config fields:

• project name
• engine endpoint
• preferred policies
• stage model overrides
• output defaults

Example JSON:

{
  "project": {
    "name": "acme-api"
  },
  "engine": {
    "url": "http://127.0.0.1:4010",
    "apiPrefix": "/api"
  },
  "policies": {
    "preferred": ["baseline", "high-assurance-reviews"]
  },
  "models": {
    "stageOverrides": {
      "implementation": {
        "providerId": "openai",
        "profileId": "gpt-5.4-coder",
        "notes": "Prefer the strongest coding profile for implementation."
      },
      "testing": {
        "providerId": "anthropic",
        "profileId": "claude-sonnet-test",
        "notes": "Bias toward faster test iteration."
      }
    }
  },
  "output": {
    "format": "pretty",
    "color": true
  }
}

In the current MVP, project-level preferred policies and stage overrides are stored locally and surfaced by CLI commands, while the active routing policy set is still selected by engine startup config.

Example YAML:

project:
  name: acme-api
engine:
  url: http://127.0.0.1:4010
  apiPrefix: /api
policies:
  preferred:
    - baseline
    - high-assurance-reviews
models:
  stageOverrides:
    implementation:
      providerId: openai
      profileId: gpt-5.4-coder
      notes: Prefer the strongest coding profile for implementation.
output:
  format: pretty
  color: true

Output Modes

The CLI supports three output modes:

• default pretty output for humans
• --json for structured JSON results and errors
• --shell for key=value or tab-separated output that works well with shell tools

Examples:

taskhelm --json engine status
taskhelm --shell version
taskhelm --shell run list

--json and --shell are mutually exclusive.

Command Reference

taskhelm version

Show the CLI version, resolved workspace, active project config, and runtime target.

taskhelm version
taskhelm --json version
taskhelm --shell version

taskhelm init

Create a local TaskHelm project config in the current directory.

taskhelm init
taskhelm init --yaml
taskhelm init --name acme-api --engine-url http://127.0.0.1:4010
taskhelm --json init --yaml

taskhelm doctor

Check user config, workspace resolution, and basic engine connectivity.

taskhelm doctor
taskhelm --json doctor

taskhelm profile

Show the active team/profile and the resolved workspace context.

taskhelm profile
taskhelm --json profile

taskhelm profile set

Persist the active team and/or profile to the user CLI config.

taskhelm profile set --team platform --name nida
taskhelm profile set --name release-bot

taskhelm policies

Show preferred policies from the local project config and the engine default policy set when available.

taskhelm policies
taskhelm --json policies

taskhelm models

Show stage model overrides from the local project config and provider health from the engine when reachable.

taskhelm models
taskhelm --json models

taskhelm config path

Show the user config path plus the resolved workspace and project config path.

taskhelm config path
taskhelm --json config path

taskhelm config show

Show the effective merged config with secrets redacted by default.

taskhelm config show
taskhelm config show --show-secrets
taskhelm --json config show

taskhelm config get

Read a single effective config value.

taskhelm config get engine.url
taskhelm config get workspace.defaultPath
taskhelm --json config get output.format

taskhelm config set

Persist a user-level config value.

taskhelm config set engine.url http://127.0.0.1:4010
taskhelm config set output.format shell
taskhelm config set profile.team platform
taskhelm config set auth.token sk-placeholder

taskhelm config init

Bootstrap the user-level CLI config file.

taskhelm config init
taskhelm config init --force --workspace C:\dev\acme-api

taskhelm engine status

Fetch a consolidated engine snapshot with health, version, and provider health.

taskhelm engine status
taskhelm --json engine status
taskhelm --shell engine status

taskhelm engine ping

Check whether the engine is reachable and measure basic request latency.

taskhelm engine ping
taskhelm --json engine ping

taskhelm task create

Create a task request from prompt text and execute it through the engine. In the current engine MVP, this creates and executes a run synchronously.

Required inputs:

• prompt text as [prompt], --prompt-file <path>, or --stdin
• --type <intent>
• --goal <goal>

Useful routing controls:

• --budget-mode <low_cost|balanced|high_assurance>
• --quality-mode <standard|high|frontier>
• --speed-mode <fast|balanced|deliberate>
• --strict-json
• --workspace <path>

Examples:

taskhelm task create "Refactor the auth middleware" --type refactor --goal "reduce coupling and improve tests"
taskhelm task create "Write onboarding docs" --type documentation --goal "ship docs" --budget-mode low_cost
taskhelm task create --prompt-file .\brief.txt --type code_generation --goal "build the first worker" --quality-mode frontier
Get-Content .\prompt.txt | taskhelm task create --stdin --type bug_fixing --goal "stabilize checkout flow"
taskhelm --json task create "Add routing metrics" --type planning --goal "capture implementation scope"

taskhelm task route-preview

Ask the engine how it would route a task without executing it.

taskhelm task route-preview "Fix flaky checkout tests" --type testing --goal "estimate routing"
taskhelm task route-preview --prompt-file .\task.txt --type code_generation --goal "see provider selection"
Get-Content .\prompt.txt | taskhelm task route-preview --stdin --type documentation --goal "preview route plan"
taskhelm --json task route-preview "Prepare release notes" --type documentation --goal "inspect routing trace"

Compatibility note:

• route-preview expects an engine build that exposes the routing simulation endpoint.
• If the connected engine does not expose it yet, the CLI returns a compatibility error with next-step guidance.

taskhelm task watch

Watch live run events over the engine SSE stream. The command stops automatically when the run reaches a terminal event.

taskhelm task watch run-abc123
taskhelm task watch run-abc123 --no-replay-existing
taskhelm --json task watch run-abc123
taskhelm --shell task watch run-abc123

taskhelm run list

List known runs, optionally filtered by lifecycle.

taskhelm run list
taskhelm run list --lifecycle completed
taskhelm --json run list --lifecycle failed
taskhelm --shell run list

taskhelm run get

Fetch a run with execution plan and persisted events.

taskhelm run get run-abc123
taskhelm --json run get run-abc123

taskhelm run logs

Fetch persisted run log events for a run.

taskhelm run logs run-abc123
taskhelm --json run logs run-abc123
taskhelm --shell run logs run-abc123

Error Model And Exit Hints

The CLI emits structured error payloads in --json mode and human-readable next-step hints in default mode.

Current error categories include:

• config and project-config failures
• validation and usage failures
• engine unavailable
• engine request rejected
• unsupported engine capability
• authentication required

Example:

taskhelm --json engine ping

Typical JSON error shape:

{
  "error": {
    "code": "engine_connection_failed",
    "message": "Failed to connect to TaskHelm Engine at http://127.0.0.1:4010. Start taskhelm-engine or update engine.url in the CLI config.",
    "exitCode": 20,
    "details": {
      "hint": "The CLI could not open an HTTP connection to the configured engine endpoint.",
      "nextSteps": [
        "Start taskhelm-engine locally or verify the remote service is reachable.",
        "Run taskhelm config get engine.url to inspect the resolved endpoint."
      ]
    }
  }
}

Development

Install dependencies from the monorepo root:

pnpm install

Useful commands for this package:

pnpm --filter @taskhelm/cli dev
pnpm --filter @taskhelm/cli build
pnpm --filter @taskhelm/cli lint
pnpm --filter @taskhelm/cli typecheck
pnpm --filter @taskhelm/cli test

Structure

taskhelm-cli/
|-- src/
|   |-- app/
|   |-- commands/
|   |-- config/
|   |-- contracts/
|   |-- engine/
|   |-- errors/
|   |-- output/
|   |-- sdk/
|   |-- tasks/
|   |-- utils/
|   `-- workspace/
|-- planned1.md
|-- planned2.md
|-- planned3.md
|-- planned4.md
|-- planned5.md
|-- planned6.md
|-- planned7.md
|-- planned8.md
`-- README.md

Roadmap Docs

• CLI Purpose And UX Principles
• Command Tree Roadmap
• Config Design
• Auth And Engine Connectivity Roadmap
• Interactive UX Roadmap
• CLI Project Integration Strategy
• CI/CD Usage Strategy
• Future Auth, Login, And Cloud Sync Design

Shared System Docs

• Shared Terminology
• Integration Map
• Product Roadmap Index