Keito CLI Integration

The Keito CLI is the runtime layer for developer and agent integrations. Use it directly when you want explicit terminal commands, JSON output, and predictable exit codes.

Install

brew install osodevops/tap/keito
keito auth login
keito auth status

If you do not use Homebrew, download a binary from the Keito CLI releases.

Authenticate

Create an API key in Keito, then run:

keito auth login

The CLI stores credentials in the local Keito config file. For agents and CI, set environment variables instead:

export KEITO_API_KEY="kto_xxxxx"
export KEITO_ACCOUNT_ID="company_id_here"

Discover Work

keito clients list
keito projects list
keito projects tasks

The API returns only the clients, projects, and tasks the authenticated credential can access. If a user or API key is not assigned to a project in Keito, the CLI cannot use that project.

Track Time

keito time start --project "Acme Website" --task "Development"
keito time running
keito time stop --notes "Implemented OAuth flow"

For work that already happened:

keito time log \
  --project "Acme Website" \
  --task "Development" \
  --duration 1:30 \
  --date 2026-05-12 \
  --notes "Implemented OAuth flow"

Agent Mode

Agents should use JSON and IDs wherever possible:

keito --json auth status
keito --json projects list
keito --json projects tasks
keito --json time session-record \
  --project "project_id_here" \
  --task "task_id_here" \
  --session-id "codex-session-123" \
  --duration-seconds 1800 \
  --source agent \
  --metadata '{"integration":"custom_agent","agent_type":"codex"}'

Use direct CLI commands when you want a simple scriptable workflow. Use the Agent Skill when you want Codex or Claude Code hooks to capture sessions automatically.

Verify

keito --json auth status
keito --json skill doctor
keito --json time list --today

keito skill doctor is useful even for CLI-first users because it reports whether the optional Agent Skill and hooks are installed.

Security

  • API keys live in the CLI config file or environment variables, not in .keito/config.yml.
  • The CLI sends Keito-Account-Id with every API request so workspace access is scoped by the authenticated company.
  • Project and task access is enforced by the Keito API.
  • Use --json in automation so errors are structured and never require parsing formatted tables.

See Also