Akleao CLI

Unified command-line interface for Akleao apps.

Commands are scoped by app:

• akleao dock … — Akleao Dock (projects, datasets, large-file uploads)
• akleao research … — Akleao Research (scaffold — not yet implemented)
• akleao <cmd> … — bare commands without an app scope default to research

Tracked in AKLEAO-43.

Install

cd cli
pip install -e .

Exposes the akleao command.

Authenticate once — every app

# Opens a browser on akleao.com; mints ONE sk_akleao_* key valid on
# both Dock and Research. Stored under the `akleao:` config section.
akleao login

# Headless / SSH:
akleao login --no-browser        # RFC 8628 device flow
akleao login --api-key sk_akleao_...

akleao whoami
akleao logout

On staging/prod, just point at the auth base — both API bases (Research + Dock) are derived automatically for akleao.com hosts:

akleao login --env staging --api-url https://staging.akleao.com
akleao login --env prod    --api-url https://akleao.com

Quickstart — Dock

# 1. Authenticate (unified login above, or the legacy per-app flow)
akleao dock auth login

# Or headless, with a pre-provisioned API key:
akleao dock auth login --api-key sk_akleao_...

# 2. List projects and datasets
akleao dock projects list
akleao dock datasets list --project <project-id>

# 3. Upload a large file directly to GCS
akleao dock datasets upload <dataset-id> ./huge-file.parquet

Configuration

All CLI config lives at ~/.config/akleao/config.yaml, with per-app nested sections (akleao: / dock: / research:), each holding named environments (default / staging / prod / …). The akleao: section is the shared bucket written by akleao login — one key + explicit dock_url / research_url per environment; the per-app sections remain for legacy per-app logins and app-specific overrides.

On first run, any legacy ~/.config/dock/config.yaml is automatically ported into the new file's dock: section.

Dock env vars

Scoped to whichever dock environment is active. They override values stored in the config file.

• DOCK_API_URL — Dock base URL (default: http://localhost:3001)
• DOCK_API_KEY — API key (format sk_akleao_...; legacy sk_dock_... keys still work)
• DOCK_USER_EMAIL — bound user email
• DOCK_ENV — named environment to target (default, staging, prod, …)

Akleao (shared) env vars

• AKLEAO_API_KEY — unified API key (overrides the stored one)
• AKLEAO_API_URL — auth/login base URL
• AKLEAO_DOCK_URL / AKLEAO_RESEARCH_URL — per-app API bases
• AKLEAO_ENV — named environment to target

Research env vars

Same pattern with a RESEARCH_ prefix.

Commands

Dock — Auth

• akleao dock auth login — default: opens a browser to authenticate
• akleao dock auth login --api-key KEY — headless, skip the browser
• akleao dock auth login --no-browser — device-flow approval (see below)
• akleao dock auth login --api-url URL — override/store the env's base URL
• akleao dock auth logout — clear credentials for the active env
• akleao dock auth whoami — print the user the stored key resolves to

Top-level shortcuts exist for convenience: akleao dock login, akleao dock whoami, akleao dock logout.

Dock — Env

• akleao dock env list — show all environments with their URL and auth state
• akleao dock env show [NAME] — details for one env (masks the API key; defaults to current)
• akleao dock env use <name> — switch which env is active
• akleao dock env add <name> --url URL — register a new env (unauthenticated)
• akleao dock env set <name> [--url URL] [--clear-auth] — update URL and/or wipe stored creds
• akleao dock env remove <name> [--yes] — drop an env

Dock — Projects

• akleao dock projects list [--limit N] [--status STATUS]
• akleao dock projects get <project-id>

Dock — Datasets

• akleao dock datasets list [--project PROJECT_ID]
• akleao dock datasets get <dataset-id>
• akleao dock datasets create <name> --project <project-id>
• akleao dock datasets files list <dataset-id>
• akleao dock datasets upload <dataset-id> <file> — direct-to-GCS upload

Research

Not yet implemented. See AKLEAO-43.

Device-flow login (--no-browser)

For SSH sessions, containers, WSL, or anywhere a local browser isn't practical:

akleao dock auth login --no-browser

The CLI prints a short user code and a verification URL (e.g. a one-click approve page). Open it on any device you're already signed into Akleao with, confirm the code, and the CLI picks up the new API key automatically. RFC 8628 under the hood — POST /api/rest/v1/dock/auth/cli/device-code → poll /device-token until the frontend's approve-page fires.

Env-var precedence

For every setting with an env-var counterpart, the order is: explicit CLI flag → DOCK_* env var → value stored in the active environment. The config file is the baseline; env vars scoped to the prefix override just the active environment (they don't leak across research/dock/etc.).

Testing

cd cli
pip install -e '.[dev]'
pytest

Tests sandbox ~/.config/akleao/ into a tmpdir and mock HTTP via respx, so running them doesn't touch your real config or hit a live backend.

How large uploads work

akleao dock datasets upload does not send bytes through the Next.js API. Instead:

1. CLI asks the backend for a v4 signed PUT URL (POST /datasets/{id}/files/upload-url)
2. CLI streams the file directly to Google Cloud Storage with a progress bar
3. CLI calls POST /datasets/{id}/files/finalize to register the file in the database

This means you can upload multi-gigabyte files without any proxy layer in the middle.

Package layout

cli/
├── pyproject.toml
├── README.md
└── akleao/
    ├── __init__.py
    ├── __main__.py           # entry point; rewrites argv for default-to-research
    ├── cli.py                # root Typer app, mounts dock + research
    ├── utils/
    │   └── config.py         # unified ~/.config/akleao/ config, per-app buckets
    ├── dock/
    │   ├── cli.py
    │   ├── api/
    │   └── commands/         # auth, datasets, projects, env_cmd
    └── research/
        └── cli.py            # scaffold — add commands here

When research commands are added, register them on akleao/research/cli.py::app — they'll be reachable at both akleao research <cmd> and (because research is the default scope) akleao <cmd>.