Metadata-Version: 2.4
Name: akleao
Version: 0.2.0
Summary: Akleao CLI — unified entry point for Akleao apps (dock, research)
Project-URL: Homepage, https://akleao.com
Project-URL: Repository, https://github.com/akleao/akleao
Project-URL: Issues, https://github.com/akleao/akleao/issues
Project-URL: Changelog, https://github.com/akleao/akleao/releases
Author-email: Akleao Team <support@akleao.com>
License: MIT
Keywords: akleao,cli,data,dock,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Akleao CLI

Unified command-line interface for [Akleao](https://akleao.com) 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

```bash
cd cli
pip install -e .
```

Exposes the `akleao` command.

## Authenticate once — every app

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

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

## Quickstart — Dock

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

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

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