# 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

```bash
brew install osodevops/tap/keito
```

### GitHub Releases

Download a binary or installer from the [keito-cli releases](https://github.com/osodevops/keito-cli/releases).

### Build from Source

```bash
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.

```bash
keito auth login
```

The login command prompts for:

| Prompt | Value |
|---|---|
| API key | A long-lived `kto_...` Keito API 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:

```bash
export KEITO_API_KEY="kto_xxxxx"
export KEITO_ACCOUNT_ID="your_company_id"
```

## Verify Credentials

```bash
keito auth status
keito auth whoami
```

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

```bash
keito auth status --json
```

## Discover Projects and Tasks

```bash
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

```bash
# 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:

```bash
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:

```bash
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.

```bash
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](/docs/integrations/skills):

```bash
keito skill install
```

## Next Steps

- [Authentication](/docs/cli/authentication) - credentials, config files, and environment variables.
- [Projects & Tasks](/docs/cli/projects-and-tasks) - how project and task resolution works.
- [Tracking Time](/docs/cli/tracking-time) - timers, manual entries, filters, and JSON output.
- [Agent Workflows](/docs/cli/agent-mode) - reliable patterns for agents and scripts.
- [Keito Agent Skill](/docs/integrations/skills) - automatic local session tracking.