droploft-shared

# Droploft v2 CLI — Shared Skill Read this before invoking any other `droploft-*` skill. It explains how the CLI is structured, how to authenticate, and the contract every command honours. ## Three-layer command model | Layer | Syntax | When to use | |---|---|---| | **1 · Flows** | `droploft <domain> +<verb>` | High-level multi-step ops (interactive picker, polling, progress). E.g. `doc +upload`, `loft +switch`. | | **2 · Resources** | `droploft <resource> <verb>` | 1:1 API mapping with full parameter control. E.g. `documents list`, `lofts get <id>`. | | **3 · Raw API** | `droploft api <METHOD> <path> [--data <json>]` | Anything not covered above. | There is also a self-describing **schema** browser: `droploft schema list|get|search`. `+` in front of a verb signals "flow". Resource verbs do not start with `+`. This visual split is intentional — flows can prompt, polls, or open a browser; resources never do. ## Authentication (Device Flow) The default login is RFC 8628 device flow — no local HTTP server, works in SSH/containers. ```bash droploft auth login # opens browser, prints user code, polls until verified droploft auth login --label "MyLaptop" # custom name for the issued API token droploft auth login --no-browser # print URL only (don't auto-open) droploft auth login --token <pat> # CI / non-TTY: skip the browser dance ``` The browser prompts the signed-in user to confirm the displayed user code. On success the CLI receives a personal API token and stores it in the OS keychain. ### Status / logout ```bash droploft auth status # verifies token via /v1/auth/me droploft auth logout # clears the keychain entry; revoke server-side via /settings?tab=api-token ``` ### CI / scripts Set environment variables instead of running `auth login`: - `DROPLOFT_TOKEN` — bypass keychain - `DROPLOFT_SERVER_URL` — override server URL - `DROPLOFT_PROFILE` — choose profile ## Profiles Each profile is a self-contained context: server URL, keychain entry, workspace, loft. ```bash droploft config use staging # switch profile droploft config set server_url https://api.example # set on active profile droploft config get server_url droploft config list # all profiles droploft config current # active profile snapshot ``` Per-call override: `--profile <name>` and `--server-url <url>` work on every command. ## Output contract Every command writes one of: - **Envelope JSON** (`--format json`, default for non-TTY): `{ok: true, data: ...}` or `{ok: false, error: {type, message, hint, status}}` to stderr. - **Table** (`--format table`, default for TTY): aligned columns, headers sorted alphabetically. - **CSV / NDJSON** (`--format csv|ndjson`): for spreadsheet / streaming consumers. Errors always go to stderr with a non-zero exit code: | Code | Meaning | |---|---| | 0 | success | | 2 | usage / validation / non-interactive without flags | | 3 | auth required | | 4 | not found | | 5 | conflict | | 6 | rate limited | | 1 | other | ## Non-interactive behaviour The CLI hard-fails any prompt when stdin/stdout is not a TTY. To stay scriptable, pass the missing parameter explicitly: | Flow | Non-TTY substitute | |---|---| | `auth login` | `--token <pat>` (or `DROPLOFT_TOKEN`) | | `loft +switch` | `--loft <id>` | | `workspace +switch` | `--workspace <id>` | ## Self-discovery If you don't know which endpoint to call, ask the CLI itself: ```bash droploft schema list # all known endpoints droploft schema list --tag documents # filter by tag droploft schema get documents.create # full spec of one endpoint droploft schema search publish # keyword search droploft api GET /v1/me/navigation # raw call, useful as a fallback ``` ## Universal flags - `--profile <name>`, `--server-url <url>` - `--format <json|table|csv|ndjson>`, `--quiet`, `--verbose`, `--no-color` - `--jq <expr>` (Layer 3 / list endpoints) — apply a jq-style filter - `--help`, `--version`