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

Eligible active internal Members and Managers can create their own key in Settings > API & Developers > Personal API keys. Enter a name, choose All permitted operations in API key access, and select Create API key. Copy the secret immediately and the Company ID from the same page. The key follows your current Keito permissions.

For an Agent identity or a key issued to another member, a workspace Administrator can create an Integration key bound to that identity. See API key setup.

Do not use the Personal read-only sync key. It cannot access tracking tasks or write time entries. Existing read-only keys and their rotation replacements stay read-only; create a new key for write access.

keito auth login

The login command prompts for:

Prompt Value
API key A full-access kto_... integration key
Account/company ID The 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.

OS Config 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 "Acme Website"

Projects can be referenced by ID, name, or code. Task definitions can be reused across the workspace, but time entries must use a task assigned to the selected project. Pass the project to keito projects tasks before choosing a task.

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 "Acme Website" --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