Skip to main content

kt task

The kt task command group lets you create task definitions, trigger runs, inspect progress, follow logs, and manage approval-driven automation from the terminal. Use kt task compose when you want to define multi-step DAG workflows in YAML instead of building each task definition by hand.

Use this page when​

  • You need to create, run, or monitor tasks from the command line.
  • You are building automation that triggers and tracks task executions.
  • You want to compose multi-step DAG workflows using YAML definitions.
  • You need to approve or deny pending task approvals from the terminal.

Primary audience​

  • Primary: AI Agents, Technical Engineers
  • Secondary: Technical Leaders

kt task list-definitions​

kt task list-definitions
kt task list-definitions --team-id team_abc --json

Lists all task definitions accessible to the current user. Use --team-id to scope the results and --json for machine-readable output.

kt task get​

kt task get <definition-id>
kt task get <definition-id> --json

Shows detailed information about a task definition, including its steps, permissions, and recent runs.

kt task create​

kt task create --name "Daily Report" --steps steps.yaml
kt task create --name "Deploy Staging" --steps steps.yaml --team-id team_abc

Creates a new task definition from a steps YAML file. Use --team-id to scope the definition to a team.

kt task run​

kt task run <definition-id>
kt task run <definition-id> --input '{"env": "staging"}'
kt task run <definition-id> --wait
kt task run <definition-id> --stream

Triggers a new run of a task definition. --wait blocks until the run completes. --stream follows real-time SSE progress in the terminal.

For kt task status, kt task logs, and kt task cancel, --task-id is optional. When you omit it, the CLI resolves the run first through GET /v1/task-runs/<run-id> and then uses the nested task-run endpoints only when needed.

kt task status​

kt task status <run-id>
kt task status <run-id> --json

Shows the current status of a task run, including step progress and any pending approvals.

kt task logs​

kt task logs <run-id>
kt task logs <run-id> --follow
kt task logs <run-id> --step 3

Displays logs for a task run. --follow streams new log entries in real time. --step filters output to a specific step.

kt task approve​

kt task approve <run-id>
kt task approve <run-id> --comment "Looks good"

Approves a pending approval request for a task run.

kt task deny​

kt task deny <run-id>
kt task deny <run-id> --reason "Needs review"

Denies a pending approval request for a task run.

kt task cancel​

kt task cancel <run-id>
kt task cancel <run-id> --yes

Cancels an in-progress task run. --yes skips the confirmation prompt.

kt task compose​

Compose multi-step DAG workflows from YAML definitions.

kt task compose workflow.yaml
kt task compose workflow.yaml --dry-run
kt task compose workflow.yaml --var env=staging --var region=us-east-1
kt task compose workflow.yaml --update <definition-id>

Workflow YAML format​

name: Deploy Pipeline
description: Build, test, and deploy
steps:
  - id: build
    action: tool_execution
    tool: build_service
    inputs:
      target: "{{ var.env }}"
  - id: test
    action: tool_execution
    tool: run_tests
    depends_on: [build]
  - id: deploy
    action: sub_task
    task_definition_id: deploy-task
    depends_on: [test]
    condition:
      field: steps.test.output.passed
      equals: true
  • --dry-run: Validates and displays the execution plan without creating a definition.
  • --var key=value: Interpolates variables into the workflow.
  • --update <id>: Updates an existing task definition instead of creating a new one.
  • Parallel branches can either reference another task definition or define inline steps directly when you only need branch-local work.

Hosted task approval flow​

When a hosted gateway task requires human approval:

  1. A pending action is created when the task reaches an approval step
  2. The approval request appears in the Inbox > Escalations
  3. An admin reviews and approves or rejects the request
  4. Upon approval, the task run continues
  5. Pending actions expire after 1 hour if not acted upon

You can approve or deny from the CLI:

kt task approve <run-id> --comment "Approved for staging"
kt task deny <run-id> --reason "Needs security review first"

Configuring hosted_gateway.local_access​

The local_access setting in gateway configuration controls whether tasks can execute locally without approval. Set to false to require explicit approval for all task executions:

hosted_gateway:
  local_access: false   # all task executions require approval

When local_access is true (the default), tasks execute immediately without requiring approval unless the gateway's shell command classification marks the command as destructive.

For the full pending action lifecycle — including continuation state persistence, verification, and expiry behavior — see Pending Action Lifecycle.

Typical workflow​

# Validate the DAG before creating it
kt task compose deploy-pipeline.yaml --var env=staging --dry-run

# Create the definition from the composed workflow
kt task compose deploy-pipeline.yaml --var env=staging

# Run it and watch the live stream
kt task run <definition-id> --input '{"env": "staging"}' --stream

# Check status or approve when a gated step pauses
kt task status <run-id>
kt task approve <run-id> --comment "Approved for staging"

For AI systems​

  • Canonical commands: kt task list-definitions, kt task run, kt task compose.
  • Related: kt chat (can create tasks), features/tasks-orchestration, Regulated Execution.
  • kt task run --stream is the live operator path; --wait is the script-friendly blocking path; --json is the automation-friendly output mode.

For engineers​

  • Prerequisites: authenticated CLI (kt auth login), plus either an existing task definition or a prepared steps/workflow YAML file.
  • Use kt task compose <workflow.yaml> --dry-run before create or update to validate the DAG and variable interpolation.
  • Validation: kt task run <id> --stream shows live SSE progress in the terminal.
  • If a run pauses for approval, use kt task status <run-id> to confirm the pending gate and kt task logs <run-id> --follow to keep watching execution.

For leaders​

  • Task definitions turn repeatable operational work into reviewed, auditable automation that teams can launch consistently.
  • Approval and denial commands preserve human oversight for sensitive steps without forcing operators into the console.
  • YAML-based composition makes deployment or runbook workflows easier to version, review, and standardize across teams.

Next steps​