CLI reference
Every onepin command, flag, and exit code.
The onepin CLI ships with pip install onepin. For task walkthroughs see the Guides; this page is the complete command surface. Run onepin <command> --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 <ID> | Show one workflow, including its definition |
onepin workflows create --name NAME | Create from a definition — --description, --definition @file.json |
onepin workflows update <ID> | Update --name, --description, or --definition @file.json (full replace) |
onepin workflows duplicate <ID> | Copy a workflow in your workspace |
onepin workflows delete <ID> [--yes] | Delete a workflow (destructive) |
onepin workflows uploads <ID> | List uploads bound to a workflow |
onepin workflows preview-run <ID> | Estimate a run’s cost without executing |
onepin workflows definition-schema | Print the JSON Schema for a workflow definition |
onepin workflows run <ID> | Start a run — --script TEXT, --source-language CODE, --watch, --timeout SECS |
Runs
| Command | What it does |
|---|---|
onepin workflows runs list <ID> | Run history — --status, --search, --sort, --order, --limit |
onepin workflows runs show <ID> <RUN> | Full run object |
onepin workflows runs status <ID> <RUN> | Status + step progress |
onepin workflows runs cancel <ID> <RUN> [--yes] | Cancel a run (destructive) |
onepin workflows runs steps <ID> <RUN> | List the run’s steps |
onepin workflows runs overview <ID> <RUN> | Per-node state |
onepin workflows runs data <ID> <RUN> | Output rows — --search, --language, --limit, --offset |
onepin workflows runs summary <ID> | Aggregate run stats — --from, --to |
onepin workflows runs download <ID> <RUN> --out FILE [--force] | Download the full export ZIP |
onepin workflows runs download-node <ID> <RUN> <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 <ID> | Show one template |
onepin templates clone <ID> [--name NAME] | Clone into a new workflow |
onepin templates create --name NAME | Create a template — --description, --category, --definition @file.json |
onepin templates update <ID> | Update --name, --description, --category, --definition |
onepin templates delete <ID> [--yes] | Delete a template (destructive) |
onepin templates favorite <ID> / unfavorite <ID> | 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 <ID> | Show one voice |
onepin voices similar <ID> | Voices similar to one — --language, --limit |
onepin voices favorite <ID> / unfavorite <ID> | 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 <ID> --workflow-id <WF> | Bind a confirmed upload to a workflow |
onepin uploads delete <ID> [--yes] | Delete an upload (destructive) |
Nodes
| Command | What it does |
|---|---|
onepin nodes list | List node types with their ports |
onepin nodes show <NODE_TYPE> | 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 <ID> | List or show workspaces |
onepin workspace create --name NAME | Create a workspace |
onepin workspace update <ID> / delete <ID> [--yes] | Update or delete (delete is destructive) |
onepin workspace settings <ID> | Read workspace settings |
onepin workspace invite / revoke-invite / invite-role / accept | Manage invites |
onepin workspace remove / set-role | Manage members |
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 for how the CLI resolves your key.