# Onepin > >- - **Type:** Skill - **Install:** `agentstack add skill-podonos-onepin-python-onepin` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [podonos](https://agentstack.voostack.com/s/podonos) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [podonos](https://github.com/podonos) - **Source:** https://github.com/podonos/onepin-python/tree/main/src/onepin/_cli/_skill/onepin - **Website:** https://onepin.ai ## Install ```sh agentstack add skill-podonos-onepin-python-onepin ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Onepin Drive a Onepin voice-workflow workspace through the `onepin` CLI. The CLI is the only integration surface — this skill teaches its contract, not a frozen command list. ## Golden rules - **Discover, don't guess.** `onepin schema` prints a JSON manifest of every command (`path`, `args`, `options`, and a `destructive` flag). Look a command up before building it; never invent flags from memory. - **Put `--json` immediately after `onepin`** — e.g. `onepin --json workflows list`. This global position works for *every* command; a trailing `--json` (e.g. `onepin whoami --json`) fails on some commands. Parse **stdout** as JSON. - **The exit code is the success signal, not stdout.** With `--json`, success prints the JSON payload to **stdout**; a failure prints a `{"error": {"code": "...", "message": "..."}}` envelope to **stderr** and exits non-zero. So: exit `0` → parse stdout; non-zero exit → read the error envelope from stderr. Don't expect an `error` key on stdout (on failure stdout is empty). - **Exit codes:** `0` ok · `1` API/runtime error · `2` usage error · `130` interrupted. - **Never run a destructive command without explicit confirmation** (see below). Don't add `--yes` to silence a prompt. ## Preflight (do this first, once) 1. `onepin --version` — if "command not found", tell the user to `pip install onepin`, then stop. 2. `onepin --json whoami` — confirms authentication. On success note `workspace_id`, `scopes`. - Unauthenticated (`NOT_LOGGED_IN` / `INVALID_API_KEY`) → tell the user to run `onepin login` (mint a key at https://app.onepin.ai/workspace/~/settings/api), then stop. - Pass `--workspace ` (or set `ONEPIN_WORKSPACE_ID`) only if the user has more than one workspace and the wrong one is active. 3. If `onepin schema` errors or the command is missing, the CLI is old — suggest `pip install -U onepin`, or fall back to `onepin --help`. 4. **Offer upgrades (advisory, never block the task).** Run `onepin upgrade-check` (it prints nothing when up to date, snoozed, offline, or disabled via `ONEPIN_NO_UPDATE_CHECK`). - On `UPGRADE_AVAILABLE `: ask with AskUserQuestion — **Upgrade now** (run `onepin upgrade-check --mark-upgrading && pip install --upgrade onepin` — the marker lets the next run confirm the new version), **Not now** (run `onepin upgrade-check --snooze` — an escalating quiet period: 24h, then 48h, then 7d), or **Don't ask again** (run `onepin upgrade-check --disable`). Continue with the task either way. - On `JUST_UPGRADED `: tell the user they're now on v`` and continue. Separately, if *any* command fails with `UPGRADE_REQUIRED` (or an HTTP 426), the SDK is too old to talk to the API — surface the message and its `pip install --upgrade` command, and stop. ## Discover, don't guess `onepin schema` → `{name, version, commands: [{path, args, options:[{flag,type,required,default,help}], destructive}]}`. Look up the exact command before building it. `destructive: true` ⇒ it has `--yes` ⇒ apply the confirmation rule below. ## Core flows Lead every command with `--json` (`onepin --json …`); summarize results for the user rather than dumping raw JSON. ### Workflows - List: `onepin --json workflows list` — filters `--status`, `--search`, `--sort`, `--order`, `--limit`. **Lists are paginated and truncated:** default `--limit` is 50, the max page is ~100 (larger values return `422 VALIDATION_ERROR`), and there is no offset/cursor — so a large set cannot be fully enumerated. Narrow with `--search`/filters; if results are capped, tell the user the list is partial rather than implying it is complete. - Inspect: `onepin --json workflows show ` - Estimate cost before running: `onepin --json workflows preview-run ` - **Run (starts a real, billable execution):** `onepin --json workflows run `. A run consumes credits and acts on the live workspace. It is *not* `--yes`-gated, so for an expensive, production, or ambiguous run, confirm with the user first (and consider `preview-run`). - Run and wait: `onepin --json workflows run --watch --timeout 300` — polls to a terminal state (`completed`/`failed`/`cancelled`) and returns the final status inline (no separate status call). Exit is non-zero if the run failed or timed out. - **Build/design a workflow:** see the GA node catalog and the *Designing a workflow* topology rules (sources → processing → generators → validators → sinks; validator pass/fail pins and retries) in [reference.md](reference.md). Discover slugs with `onepin nodes list` — never invent them. ### Runs - `onepin --json workflows runs list ` - `onepin --json workflows runs status ` - `onepin --json workflows runs data ` (output rows) - Download outputs to a file: `onepin workflows runs download --out export.zip` (atomic; refuses to overwrite without `--force`). ### Voices - `onepin --json voices list` — filters `--provider`, `--gender`, `--language`, `--search`. `--language` accepts only specific comma-separated codes (e.g. `en-us`, `en-gb`, `en`); an unsupported code returns `422` — don't guess regions, and note a voice's own `supported_languages` may be broader than the filter codes. Same pagination cap as above (default 50, ~100 max, no offset), so the full catalog can't be listed in one call. - `onepin --json voices show ` · `onepin --json voices similar ` ### Templates - `onepin --json templates list` — filters `--category`, `--sort`, `--search` - `onepin --json templates show ` ## Destructive operations (require explicit confirmation) `workflows delete`, `templates delete`, `uploads delete`, `workspace delete`, `workflows runs cancel`, `workspace members remove`, `workspace members revoke-invite` — all irreversible. Procedure: 1. **Resolve the exact target.** Confirm the id/name actually exists (via `--search` or a `show`); never act on a fuzzy match — `"test"` is not `"test-tts"`. 2. **Get an explicit yes.** State plainly what will be deleted/cancelled and that it cannot be undone. 3. **Then run with `--yes`** (e.g. `onepin --json workflows delete --yes`). Without `--yes` the CLI emits an interactive prompt that can hang in a non-interactive shell, so confirm with the user first, then pass `--yes`. A `CONFIRMATION_REQUIRED` error means "stop and ask" — never "retry with `--yes`." ## Output & errors - On exit `0`, parse stdout as JSON. On any non-zero exit, read the error envelope from **stderr** — `{"error":{"code":"NOT_FOUND","message":"..."}}` (also `VALIDATION_ERROR`, `FORBIDDEN`, `RATE_LIMITED`, `NOT_LOGGED_IN`, `CONFIRMATION_REQUIRED`). - Report failures to the user as `code: message`, plainly. For the full command catalog and recipes (workflow definitions, uploads, workspace + members, usage, nodes), see [reference.md](reference.md) or run `onepin schema`. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [podonos](https://github.com/podonos) - **Source:** [podonos/onepin-python](https://github.com/podonos/onepin-python) - **License:** MIT - **Homepage:** https://onepin.ai Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-podonos-onepin-python-onepin - Seller: https://agentstack.voostack.com/s/podonos - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.