originai

The CLI for the Origin product-design-spec platform: authorize (login), read/write specs, sync releases, and validate RPML. Coding agents call it repeatedly via shell to interact with Origin's spec API.

Quick Start

# Link this repo to an Origin project — writes .origin.json + SKILL.md
# (no token needed if --project is given).
npx originai link --project <project-id>   # first bind
bunx originai link                         # refresh skill files (already linked)
bun update originai                        # upgrade the CLI package (when installed)

# Agent commands — prefer bunx (fast, ~40ms) over npx (~1.2s per call)
bunx originai list-documents
bunx originai list-documents --read-type workspace          # live tree (pre-release)
bunx originai get-document --id <file-id>
bunx originai get-diff                                       # read-only — does NOT advance release_hash
bunx originai sync                                           # advance release_hash after implementing a diff
bunx originai grep --pattern "button"
bunx originai find --file-pattern "login"
bunx originai validate --content "<rpml>...</rpml>"
bunx originai create-project --name "Checkout"
bunx originai write-document --name "README.rpml" --content "<rpml>...</rpml>"

How It Works

The link command writes .origin.json (project config) and agent instruction files (SKILL.md, CLAUDE.md, etc.) into the project. Coding agents then call the runtime commands repeatedly via shell to interact with Origin's design spec API.

Token

Run npx originai login — it opens your browser to authorize and stores a token in ~/.origin/settings.json (never committed). The CLI reads it automatically. (CI: set ORIGIN_TOKEN=oat_... in .env instead; get a token at https://getoriginai.com/settings/tokens.)

Token resolution (in order, for runtime commands):

1. --token flag
2. ORIGIN_TOKEN in .env (current directory, gitignored) — CI
3. ~/.origin/settings.json (user home, never committed) — originai login

Project resolution (in order)

1. --project flag
2. project_id in .origin.json (current directory)

Commands

Prefer bunx originai (fast, ~40ms) over npx originai (~1.2s per call). Both invoke the same binary.

Short aliases and flags are additive — the long names keep working. Aliases: ls→list-projects, ls-docs→list-documents, get→get-document, create→create-project, write→write-document, delete/rm→delete-document, diff→get-diff. Short flags: -p project, -i file id, -n name, -c content, -d description.

| Command | Description | |---------|-------------| | link | Bind this repo to a project, or (no flags + existing .origin.json) refresh skill/instruction files only. Package upgrades: bun update originai | | list-projects (ls) | List accessible projects | | create-project (create) | Create a new empty project (-n/--name, optional -d/--description; read-write) | | list-documents (ls-docs) | File tree of a project (latest release, or --read-type workspace for the live tree); -p <project-id> | | get-document (get) | Single file with content (-i/--id <file-id>) | | get-diff (diff) | Diff between two release snapshots (read-only; auto-reads base hash from .origin.json, target = latest). Each added/modified/renamed file embeds to-side full content by default (plus unified diff); --content-mode none\|to\|both. --from-hash/--to-hash (or positional). --sync advances the hash | | sync | Advance release_hash to the latest release (after implementing a diff) | | grep | Search content across a project's files (--pattern "<regex>", -p <project-id>) | | find | Find files by name in a project (--file-pattern "<regex>", -p <project-id>) | | validate | Validate RPML — -c/--content "<rpml>" (inline, local, no network/token) or -i/--id <file-id> (released document, remote) | | write-document (write) | Create/update file (-n/--name, -c/--content, optional -i/--id, --parent-id) | | delete-document (delete, rm) | Delete file (-i/--id <file-id>) | | delete-documents | Batch delete files (--ids <id1>,<id2>,...) |

Read source

Read commands default to the latest published release snapshot. Two options change the source:

• --read-type workspace — read the live rpml_files tree instead of a release. Use this when indexing a pre-release project (no release yet) to read back what you just wrote with write-document.
• --release-tag <hash> — pin a release read to a specific published release by its hash.

Files

| File | Contents | Commit? | |------|----------|---------| | .origin.json | api_url, project_id, release_hash | Yes | | ~/.origin/settings.json | Access token (via originai login) | No (user home) | | .env → ORIGIN_TOKEN=oat_... | Access token (CI fallback) | No (gitignored) | | .agents/skills/origin-product-spec-management/SKILL.md | Agent instructions | Yes | | .agents/skills/origin-product-spec-management/rpml/ | RPML references + methodology prompts | Yes |

link flags

| Flag | Description | |------|-------------| | (none) | If .origin.json already has project_id, refresh installed skill files only (SKILL.md / CLAUDE.md / … + RPML assets). Preserves release_hash. | | --project, -p | Project ID — first bind / re-bind (skips token prompt if provided) | | --token, -t | Access token (only needed to list projects) | | --api-url | Override API URL | | --claude-code | Also write CLAUDE.md | | --codex | Also write AGENTS.md | | --cursor | Also write .cursorrules | | --skill | Write standard SKILL.md (default on first bind) | | --all | Write all instruction files |

Upgrade checklist

bun update originai          # or: bunx originai@latest …
bunx originai link           # rewrite local SKILL.md / rpml/ from the new package

skills.sh

This skill is also discoverable via skills.sh using the well-known endpoint:

npx skills add https://getoriginai.com

Development

bun run build    # bundle → dist/
bun test         # run unit tests
bun run dev      # run from source

API

All read commands operate on the latest published release snapshot by default, not the live workspace. Pass --read-type workspace to read the live rpml_files tree (e.g. when indexing a pre-release project). Write commands (write-document, delete-document) modify the live workspace (requires read-write token) only before the first release is published. Once a release exists, write commands return 403 — specs must be edited in the Origin workbench to prevent stale-snapshot overwrites.

get-diff is read-only — it shows the diff since your release_hash but does not advance the pointer. By default each non-deleted change includes the to-side full file body (content) so agents can implement without a follow-up get-document loop; use --content-mode none for meta+unified-diff only. release_hash means "the code reflects this release", so only advance it once the diff is actually implemented: run sync (or get-diff --sync) after implementing.

Indexing a codebase → Origin (Workflow C)

When the Origin project has no published release, the agent reads the codebase and writes specs directly to Origin — no local .rpml files. The first document is always README.rpml (mode="doc"), a product-design document covering overview, functional modules, page/route planning, interaction flows, and permissions. Only after README.rpml does the agent proceed to prototype screen specs (one .rpml per page). The flow: author RPML content inline → validate --content → write-document --content. After writing, remind the user to publish a release in Origin. Once published, the agent's write access is closed — further spec edits happen in the Origin workbench.