CLI: Troubleshooting

Use --json when debugging automated workflows. JSON errors include an exit code and, when available, a recovery suggestion.

Check Authentication First

keito auth status --json

If credentials are missing:

{"authenticated": false}

Fix it with either:

keito auth login

or:

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

Invalid API Key or Company ID

Symptoms:

keito auth whoami exits with code 1
API requests return unauthorized or forbidden errors
keito auth status --json shows "api_key_valid": false

Fix:

Create or copy a valid API key from Settings > API & Developers.
Copy the Company ID from the same page.
Re-run keito auth login or update your environment variables.

Timer Already Running

keito time start exits with code 3 when a timer already exists.

Inspect it:

keito time running --json

Then either stop it:

keito time stop --notes "Completed previous session" --json

or discard it:

keito time stop --discard --json

No Running Timer

keito time stop exits with code 4 when there is no active timer.

Check first in scripts:

keito time running --json

When no timer is active, the output is:

{"running": false}

Project or Task Not Found

Refresh discovery data:

keito projects list --json
keito projects tasks --json

Use project and task IDs in automation. Names and codes are convenient for humans but can become ambiguous.

Bad Duration

keito time log accepts decimal hours or HH:MM.

Valid examples:

keito time log --project "Acme Website" --task "Development" --duration 1.5
keito time log --project "Acme Website" --task "Development" --duration 1:30

Config File Problems

If the CLI exits with code 8, inspect the config file:

OS	Path
macOS	`~/Library/Application Support/keito/config.toml`
Linux	`~/.config/keito/config.toml`
Windows	`%APPDATA%\keito\config.toml`

The minimum valid config is:

api_key = "kto_xxxxx"
account_id = "company_id_here"

Network and Server Errors

Code	Meaning	Recovery
`5`	Rate limited	Retry after a short delay
`6`	Keito API server error	Retry with backoff
`7`	Network error or timeout	Check connectivity and retry

The CLI retries transient network and server errors before returning a final error.

Expense Commands Missing

The current CLI tracks time only. It does not include expense commands. Use the Keito web app, Expenses API, Node SDK, or Python SDK for expense and LLM usage logging.