CLI: Getting Started

The Keito CLI tracks billable time against the production Keito API v2 from a terminal, script, CI job, or agent workflow.

Production API base URL: https://app.keito.ai

Install

Homebrew

brew install osodevops/tap/keito

GitHub Releases

Download a binary or installer from the keito-cli releases.

Build from Source

git clone https://github.com/osodevops/keito-cli.git
cd keito-cli
cargo build --release

The binary is written to target/release/keito.

Authenticate

Create an API key and copy your Company ID from Settings > API & Developers > Company ID in Keito.

keito auth login

The login command prompts for:

PromptValue
API keyA long-lived kto_... Keito API key
Account/company IDThe Company ID from Keito

keito auth login validates the key against the production API and saves credentials in the local config file. The CLI does not use the macOS Keychain or a system keyring.

OSConfig path
macOS~/Library/Application Support/keito/config.toml
Linux~/.config/keito/config.toml
Windows%APPDATA%\keito\config.toml

For agents and CI, prefer environment variables so the command can run without prompts:

export KEITO_API_KEY="kto_xxxxx"
export KEITO_ACCOUNT_ID="your_company_id"

Verify Credentials

keito auth status
keito auth whoami

Use JSON output when another tool or agent needs to consume the result:

keito auth status --json

Discover Projects and Tasks

keito projects list
keito projects tasks

Projects can be referenced by ID, name, or code. Tasks are workspace-global in Keito, not scoped to a single project.

Track Time

# Start a running timer
keito time start --project "Acme Website" --task "Development"

# Check the active timer
keito time running

# Stop and save elapsed time
keito time stop --notes "Implemented OAuth flow"

For work that already happened, log a completed entry:

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

Agent Quick Start

Agents should use JSON output and deterministic exit codes:

keito auth status --json
keito projects list --json
keito projects tasks --json
keito time running --json
keito time start --project "Acme Website" --task "Development" --json
# agent performs work
keito time stop --notes "Implemented OAuth flow" --json

Use keito time session-record for completed agent sessions. It writes source=agent by default and uses metadata.session_id for idempotent updates.

keito time session-record \
  --project "project_id_here" \
  --task "task_id_here" \
  --session-id "codex-123" \
  --duration-seconds 1800 \
  --metadata '{"integration":"custom_agent","agent_type":"codex"}' \
  --json

For automatic Codex and Claude Code hooks, install the Keito Agent Skill:

keito skill install

Next Steps