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:

  1. Verify that you selected All permitted operations when creating the key and that it belongs to the intended identity and workspace. If you need a replacement, eligible Members and Managers can create their own under Settings > API & Developers > Personal API keys; an Administrator issues keys for Agent identities or other members. See API key setup.
  2. Copy the Company ID from the same page.
  3. Re-run keito auth login or update your environment variables.

Personal Read-Only Sync Key Rejected

Keito CLI v0.1.8 and later reports that a personal read-only sync key cannot authenticate the tracking CLI. This is expected: the key cannot access /api/v2/tasks or create, update, stop, or discard time entries.

There is no permission toggle that upgrades the sync key, and rotating it keeps it read-only. Eligible Members and Managers can create a new key under Settings > API & Developers > Personal API keys, choosing All permitted operations in API key access. For an Agent identity, ask an Administrator to issue a key bound to that Agent. Replace the old CLI credentials with the new key, then run:

keito auth login
keito auth status --json

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 <PROJECT> --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.