> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://onepin.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://onepin.ai/docs/_mcp/server. # CLI reference The `onepin` CLI ships with `pip install onepin`. For task walkthroughs see the [Guides](/docs/guides/run-a-workflow); this page is the complete command surface. Run `onepin --help` for the same on the terminal. ## Global flags Accepted by every command: | Flag | Purpose | | ---------------------- | ------------------------------------------------------------- | | `--api-key TEXT` | Use this key (beats env var and the stored credentials file) | | `--base-url TEXT` | Override the API base URL (default `https://api.onepin.ai`) | | `--json` | Emit JSON to stdout instead of tables (the unwrapped `.data`) | | `--yes` | Skip the confirmation prompt on destructive commands | | `--verbose` / `-v` | Log HTTP details to stderr (auth redacted) | | `--version` / `--help` | Print version / help and exit | Errors go to stderr, data to stdout. `NO_COLOR=1` disables ANSI. Destructive commands prompt unless `--yes`; in `--json` mode they never prompt — they fail with `CONFIRMATION_REQUIRED` unless `--yes` is given. ## Auth | Command | What it does | | ------------------------------------------- | ---------------------------------------------------------------------------------- | | `onepin login [--key KEY] [--base-url URL]` | Validate a key and save it to `~/.onepin/credentials` (prompts if `--key` omitted) | | `onepin logout` | Delete the stored credentials file | | `onepin whoami` | Show the resolved key's source, workspace, and scopes | ## Workflows | Command | What it does | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onepin workflows list` | List workflows — `--status`, `--search`, `--sort {name,updated_at,runs_count}`, `--order {asc,desc}`, `--limit` | | `onepin workflows show ` | Show one workflow, including its definition | | `onepin workflows create --name NAME` | Create from a definition — `--description`, `--definition @file.json`. (`--name` is required by the CLI; the REST API lets you omit a name and have one generated) | | `onepin workflows update ` | Update `--name`, `--description`, or `--definition @file.json` (full replace) | | `onepin workflows duplicate ` | Copy a workflow in your workspace | | `onepin workflows delete [--yes]` | Delete a workflow *(destructive)* | | `onepin workflows uploads ` | List uploads bound to a workflow | | `onepin workflows preview-run ` | Estimate a run's cost without executing | | `onepin workflows definition-schema` | Print the JSON Schema for a workflow definition | | `onepin workflows run ` | Start a run — `--script TEXT`, `--source-language CODE`, `--watch`, `--timeout SECS`. `--watch` ends on `completed` / `failed` / `cancelled` only, so it keeps waiting on a [paused](/docs/guides/run-a-workflow#runs-can-pause) run until `--timeout` | ### Runs | Command | What it does | | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `onepin workflows runs list ` | Run history — `--status`, `--search`, `--sort`, `--order`, `--limit` | | `onepin workflows runs show ` | Full run object | | `onepin workflows runs status ` | Status + step progress | | `onepin workflows runs cancel [--yes]` | Cancel a run *(destructive)* | | `onepin workflows runs steps ` | List the run's steps | | `onepin workflows runs overview ` | Per-node state | | `onepin workflows runs data ` | Output rows — `--search`, `--language`, `--limit`, `--offset` | | `onepin workflows runs summary ` | Aggregate run stats — `--from`, `--to` | | `onepin workflows runs download --out FILE [--force]` | Download the full export ZIP | | `onepin workflows runs download-node --out FILE [--force]` | Download one node's output | ## Templates | Command | What it does | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onepin templates list` | List gallery templates — `--category {media,creative,business,education,wellness}`, `--search`, `--sort {popular,recent,name}`, `--favorites-only`, `--limit` | | `onepin templates show ` | Show one template | | `onepin templates clone [--name NAME]` | Clone into a new workflow | | `onepin templates create --name NAME` | Create a template — `--description`, `--category`, `--definition @file.json` | | `onepin templates update ` | Update `--name`, `--description`, `--category`, `--definition` | | `onepin templates delete [--yes]` | Delete a template *(destructive)* | | `onepin templates favorite ` / `unfavorite ` | Manage favorites | ## Voices | Command | What it does | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onepin voices list` | List voices — `--language`, `--provider`, `--gender {male,female,neutral}`, `--favorites-only`, `--search`, `--limit` (comma-separated where it makes sense) | | `onepin voices show ` | Show one voice | | `onepin voices similar ` | Voices similar to one — `--language`, `--limit` | | `onepin voices favorite ` / `unfavorite ` | Manage favorites | ## Uploads | Command | What it does | | ------------------------------------------------------------------ | ------------------------------------- | | `onepin uploads create --file PATH --category {script,dictionary}` | Upload a file via the presigned flow | | `onepin uploads confirm --workflow-id ` | Bind a confirmed upload to a workflow | | `onepin uploads delete [--yes]` | Delete an upload *(destructive)* | ## Nodes | Command | What it does | | ------------------------------- | ------------------------------------ | | `onepin nodes list` | List node types with their ports | | `onepin nodes show ` | Full config schema for one node type | ## Usage | Command | What it does | | -------------------------- | ----------------------------------------------------------------------------------------------- | | `onepin usage summary` | Usage summary — `--range {30d,60d,90d}`, `--activity-view {daily,weekly,monthly}`, `--timezone` | | `onepin usage by-language` | Usage by language — same flags | | `onepin usage activity` | Activity feed — `--range`, `--type`, `--user-id`, `--limit`, `--cursor`, `--timezone` | ## Workspace Team and account management (requires the matching workspace scopes): | Command | What it does | | ---------------------------------------------------------------------- | ------------------------------------------ | | `onepin workspace list` / `show ` | List or show workspaces | | `onepin workspace create --name NAME` | Create a workspace | | `onepin workspace update ` / `delete [--yes]` | Update or delete *(delete is destructive)* | | `onepin workspace settings ` | Read workspace settings | | `onepin workspace invite` / `revoke-invite` / `invite-role` / `accept` | Manage invites | | `onepin workspace remove` / `set-role` | Manage members | ## Skill Install the bundled [agent skill](/docs/get-started/agent-skill) into your AI coding tool. These are local filesystem operations — no API key, no network, so they work offline. | Command | What it does | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onepin skill install` | Install the skill — `--tool {claude,cursor,codex,copilot,gemini}` (repeatable), `--all`, `--project`, `--force`. With no flags, installs into every tool detected under `$HOME`, falling back to Claude Code | | `onepin skill path` | Show where the skill is (or would be) installed — same `--tool` / `--all` / `--project` flags. Writes nothing | | `onepin skill uninstall [--yes]` | Remove the installed skill folder *(destructive)* — same selection flags. Idempotent | ## Schema | Command | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `onepin schema` | Print the JSON manifest of every command — `path`, `args`, `options`, and a `destructive` flag per command. This is what the agent skill reads instead of guessing flags | ## Exit codes | Code | Meaning | | ----- | ------------------------------------------------- | | `0` | Success | | `1` | Runtime error — auth, network, server, validation | | `2` | Usage error — unknown flag or invalid value | | `130` | Interrupted (`Ctrl+C`) | See [Authentication](/docs/get-started/authentication) for how the CLI resolves your key.