Keito CLI Integration

The Keito CLI is the command-line runtime for human, script, CI, and agent workflows. Use it directly when you want explicit commands, JSON output, and predictable exit codes.

What It Does

The CLI can:

Authenticate a local user or API key.
List companies, clients, projects, and tasks the credential can access.
Start, stop, and inspect timers.
Log time that has already happened.
Log expenses in automation workflows.
Return structured JSON for agents and scripts.
Support the Keito Agent Skill hooks.

How It Works

The CLI talks to the Keito API using either an interactive user login or an API key. Every command is scoped to the selected Keito company account and the credential’s permissions.

For humans, the CLI is a direct timer and time-entry tool. For scripts and agents, use --json, stable IDs, and environment variables so commands can run without interactive prompts.

Connect The CLI

Install the CLI and authenticate once:

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.

For interactive use, 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 And Automation Mode

Agents and scripts should use --json and stable 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.

Disconnect Or Remove The CLI

To stop the current machine from using your interactive Keito login:

keito auth logout

For automation, remove KEITO_API_KEY and KEITO_ACCOUNT_ID from the environment, secret store, or CI settings where they were configured. If the API key is no longer needed, revoke it in Keito so it cannot be used again.

To remove the CLI binary itself, uninstall it with the package manager you used to install it. For Homebrew:

brew uninstall keito

Existing time entries created by the CLI remain in Keito after logout or uninstall.

Security

API keys live in the CLI config file or environment variables, not in .keito/config.yml.
The CLI sends the selected account ID with API requests 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 do not require parsing formatted tables.