ktsu CLI Reference

ktsu is the command-line interface for the Kimitsu agentic pipeline framework. Use it to start services, invoke workflows, validate configuration, inspect runs, and scaffold new projects.

Global Service Ports

Service	Default Port	Env Override
Orchestrator	5050	`KTSU_ORCHESTRATOR_PORT`
Agent Runtime	5051	`KTSU_RUNTIME_PORT`
LLM Gateway	5052	`KTSU_GATEWAY_PORT`

Most commands that contact a running service accept --orchestrator (default: http://localhost:5050) and respect KTSU_ORCHESTRATOR_URL.

Commands

ktsu start — Start one or all services
ktsu validate — Validate configuration files
ktsu invoke — Trigger a workflow run
ktsu runs — List workflow runs
ktsu runs get — Inspect a specific run
ktsu workflow tree — Visualize workflow dependencies
ktsu lock — Generate a lockfile
ktsu new project — Scaffold a new project
ktsu hub — Interact with the Kimitsu Hub (requires KTSU_HUB_ENABLED=true)

`ktsu start`

Start one or all Kimitsu services.

Running ktsu start with --all launches the Orchestrator, Agent Runtime, and LLM Gateway in a single process. Alternatively, start each service individually using subcommands.

`ktsu start --all`

Starts all three services in a single process.

ktsu start --all --env environments/dev.env.yaml

Flag	Default	Description
`--all`	`false`	Start orchestrator, gateway, and runtime together
`--env`	`""`	Path to environment config (e.g. `environments/dev.env.yaml`)
`--workflow-dir`	`./workflows`	Path to workflow directory
`--project-dir`	`.`	Project root for resolving agent/server paths (env: `KTSU_PROJECT_DIR`)
`--own-url`	`""`	Orchestrator's own URL for callbacks (env: `KTSU_OWN_URL`)
`--orchestrator-host`	`""`	Orchestrator bind host (env: `KTSU_ORCHESTRATOR_HOST`)
`--orchestrator-port`	`5050`	Orchestrator port (env: `KTSU_ORCHESTRATOR_PORT`)
`--store-type`	`memory`	State store: `memory` or `sqlite` (env: `KTSU_STORE_TYPE`)
`--db-path`	`ktsu.db`	Database path when using sqlite (env: `KTSU_DB_PATH`)
`--gateway-config`	`gateway.yaml`	Path to gateway config
`--gateway-host`	`""`	Gateway bind host (env: `KTSU_GATEWAY_HOST`)
`--gateway-port`	`5052`	Gateway port (env: `KTSU_GATEWAY_PORT`)
`--runtime-host`	`""`	Runtime bind host (env: `KTSU_RUNTIME_HOST`)
`--runtime-port`	`5051`	Runtime port (env: `KTSU_RUNTIME_PORT`)

`ktsu start orchestrator`

Starts only the Orchestrator service.

ktsu start orchestrator --env environments/dev.env.yaml --port 5050

Flag	Default	Description
`--env`	`""`	Path to environment config
`--workflow-dir`	`./workflows`	Path to workflow directory
`--host`	`""`	Bind host (env: `KTSU_ORCHESTRATOR_HOST`)
`--port`	`5050`	Listen port (env: `KTSU_ORCHESTRATOR_PORT`)
`--runtime-url`	`""`	Agent runtime URL (env: `KTSU_RUNTIME_URL`)
`--gateway-url`	`""`	LLM gateway URL (env: `KTSU_GATEWAY_URL`)
`--own-url`	`""`	Orchestrator's public URL for callbacks (env: `KTSU_OWN_URL`)
`--project-dir`	`.`	Project root (env: `KTSU_PROJECT_DIR`)
`--store-type`	`memory`	State store: `memory` or `sqlite` (env: `KTSU_STORE_TYPE`)
`--db-path`	`ktsu.db`	Database path for sqlite (env: `KTSU_DB_PATH`)
`--workspace`	—	Additional workspace root; repeatable
`--no-hub-lock`	`false`	Ignore `ktsuhub.lock.yaml` even if present

`ktsu start runtime`

Starts only the Agent Runtime service.

ktsu start runtime --orchestrator http://localhost:5050

Flag	Default	Description
`--orchestrator`	`http://localhost:5050`	Orchestrator URL (env: `KTSU_ORCHESTRATOR_URL`)
`--gateway`	`http://localhost:5052`	LLM gateway URL (env: `KTSU_GATEWAY_URL`)
`--host`	`""`	Bind host (env: `KTSU_RUNTIME_HOST`)
`--port`	`5051`	Listen port (env: `KTSU_RUNTIME_PORT`)

`ktsu start gateway`

Starts only the LLM Gateway service.

ktsu start gateway --config gateway.yaml --port 5052

Flag	Default	Description
`--config`	`gateway.yaml`	Path to gateway config
`--host`	`""`	Bind host (env: `KTSU_GATEWAY_HOST`)
`--port`	`5052`	Listen port (env: `KTSU_GATEWAY_PORT`)

`ktsu validate`

Validates all workflow, agent, server, and gateway YAML files in the project. Checks schema correctness, DAG cycle detection, depends_on references, and environment variable scoping rules.

ktsu validate
ktsu validate . --env environments/dev.env.yaml
ktsu validate --graph   # output a Mermaid dependency graph

Flag	Default	Description
`--env`	`""`	Path to environment config to validate
`--workflow-dir`	`""`	Directory of `*.workflow.yaml` files (defaults to `<project-dir>/workflows`)
`--project-dir`	`.`	Project root for resolving agent/server paths (env: `KTSU_PROJECT_DIR`)
`--workspace`	—	Additional workspace root to validate; repeatable
`--no-hub-lock`	`false`	Ignore `ktsuhub.lock.yaml` even if present
`--graph`	`false`	Output a Mermaid graph of the workflow DAG instead of a status report

The command prints a grouped summary — Workflows, Agents, Servers, Systems — with OKAY / FAIL per file and exits non-zero if any errors are found.

`ktsu invoke`

Triggers a workflow run on a running Orchestrator and prints the run_id. Optionally polls until the run completes and prints the full result envelope.

ktsu invoke support-triage --input '{"message": "help", "user_id": "123"}'
ktsu invoke support-triage --input '{"message": "help", "user_id": "123"}' --wait

Flag	Default	Description
`--input`	`{}`	JSON input for the workflow
`--wait`	`false`	Poll until the run completes, then print the result
`--orchestrator`	`http://localhost:5050`	Orchestrator URL (env: `KTSU_ORCHESTRATOR_URL`)

`ktsu runs`

Lists recent workflow runs from the Orchestrator, with optional filters.

ktsu runs
ktsu runs --workflow support-triage --status failed --limit 20

Flag	Default	Description
`--orchestrator`	`http://localhost:5050`	Orchestrator URL (env: `KTSU_ORCHESTRATOR_URL`)
`--workflow`	`""`	Filter by workflow name
`--status`	`""`	Filter by status: `pending`, `running`, `complete`, `failed`
`--limit`	`0`	Max results to return (orchestrator default: 50)

Output columns: RUN ID, WORKFLOW, STATUS, STARTED, DURATION.

`ktsu runs get`

Fetches and prints the full run envelope for a specific run ID.

ktsu runs get <run_id>

Flag	Default	Description
`--orchestrator`	`http://localhost:5050`	Orchestrator URL (env: `KTSU_ORCHESTRATOR_URL`)

Output is pretty-printed JSON containing the run status, step outputs, and any errors.

`ktsu workflow tree`

Prints the full dependency tree of a workflow — sub-workflows, agents, and tool servers — as an indented tree. Useful for understanding what a workflow pulls in before running it.

ktsu workflow tree workflows/support-triage.workflow.yaml
ktsu workflow tree workflows/support-triage.workflow.yaml --json

Flag	Default	Description
`--json`	`false`	Output the tree as JSON instead of a text tree

`ktsu lock`

Generates or updates ktsu.lock.yaml with pinned versions of all project dependencies.

ktsu lock

Note: This command is not yet implemented and currently prints a placeholder message.

`ktsu new project`

Scaffolds a new Kimitsu project with the standard directory structure and starter files.

ktsu new project my-project

Creates the following files under ./my-project/:

File	Purpose
`workflows/<name>.workflow.yaml`	Starter workflow
`agents/placeholder.agent.yaml`	Placeholder agent
`environments/dev.env.yaml`	Development environment config
`gateway.yaml`	LLM gateway config
`servers.yaml`	Tool server manifest
`ktsuhub.yaml`	Hub publishing config

`ktsu hub`

Interact with the Kimitsu Hub workflow registry. This command group is only available when KTSU_HUB_ENABLED=true is set in the environment.

KTSU_HUB_ENABLED=true ktsu hub <subcommand>

`ktsu hub login`

Authenticate with GitHub.

ktsu hub login

Note: Not yet implemented.

`ktsu hub install`

Install a workflow from the Kimitsu Hub or a git repository.

ktsu hub install owner/repo-name
ktsu hub install owner/repo-name@v1.2.0
ktsu hub install https://github.com/owner/repo.git

Flag	Default	Description
`--cache-dir`	`~/.ktsu/cache`	Local cache directory (env: `KTSU_CACHE_DIR`)
`--dry-run`	`false`	Preview changes without installing

Installed entries are recorded in ktsuhub.lock.yaml.

`ktsu hub update`

Re-resolves all entries in ktsuhub.lock.yaml to their latest matching commits.

ktsu hub update
ktsu hub update --latest

Flag	Default	Description
`--latest`	`false`	Also update pinned version entries to their latest releases
`--dry-run`	`false`	Preview changes without writing

`ktsu hub publish`

Publish workflows to the Kimitsu Hub.

ktsu hub publish

Note: Not yet implemented.

`ktsu hub search`

Search available workflows on the Kimitsu Hub.

ktsu hub search summarization

Flag	Default	Description
`--tag`	`""`	Filter results by tag
`--limit`	`10`	Number of results to return

Note: Not yet implemented.

Variable Substitution in Workflows

Workflow YAML files support {{ expr }} interpolation in string values. See workflow.yaml for full details.

Syntax	Scope	Description
`{{ params.NAME }}`	All workflows	Workflow input parameter
`{{ env.NAME }}`	Root workflows only	Declared environment variable
`{{ step.ID.FIELD }}`	All workflows	Output field from a completed step

JMESPath expressions (in condition: or transform expr:) use bare syntax without {{ }}.

Revised April 2026

View as Markdown

Global Service Ports​

Commands​

ktsu start​

ktsu start --all​

ktsu start orchestrator​

ktsu start runtime​

ktsu start gateway​

ktsu validate​

ktsu invoke​

ktsu runs​

ktsu runs get​

ktsu workflow tree​

ktsu lock​

ktsu new project​

ktsu hub​

ktsu hub login​

ktsu hub install​

ktsu hub update​

ktsu hub publish​

ktsu hub search​

Variable Substitution in Workflows​

Global Service Ports

Commands

`ktsu start`

`ktsu start --all`

`ktsu start orchestrator`

`ktsu start runtime`

`ktsu start gateway`

`ktsu validate`

`ktsu invoke`

`ktsu runs`

`ktsu runs get`

`ktsu workflow tree`

`ktsu lock`

`ktsu new project`

`ktsu hub`

`ktsu hub login`

`ktsu hub install`

`ktsu hub update`

`ktsu hub publish`

`ktsu hub search`

Variable Substitution in Workflows