CLI reference
Every command and flag of pinrail, from the same definition pinrail --help prints. For the commands in use, see The CLI.
Global flags
Section titled “Global flags”Every command accepts these.
| Argument | Description |
|---|---|
--url <URL> | The server’s URL [default: PINRAIL_URL, then the address in the running server’s server.json, then http://127.0.0.1:4747]. Env: PINRAIL_URL. |
--pretty | Indent the JSON output. Requires --json. |
--json | Print JSON instead of Markdown, for a script or tool that processes the result. PINRAIL_JSON=1 sets this for a whole session. Env: PINRAIL_JSON. |
--verbose | Also report each step on stderr, such as the origin read from git, the server started, the files uploaded and where files were written. Env: PINRAIL_VERBOSE. |
Commands
Section titled “Commands”pinrail ask
Section titled “pinrail ask”Ask the person one or more short questions, wait for the answers and print them.
Each question is followed by its own options, up to the next --ask:
pinrail ask "Deploy to staging or production?" \ --choice staging --choice production --recommend staging \ --ask "Keep the old endpoint for a release?" --yes-no \ --ask "What should the new endpoint be called?"The questions are independent: the person answers them in any order, and can leave some unanswered. Ask a question that depends on another answer with another pinrail ask, once you have that answer. The person can also add a note to each answer, or answer a question with choices in their own words.
The command prints the answers: with one question, only the answer; with several, each under its question; then the person’s comment on them all, if they wrote one. With --json, it prints the whole review, with the answers in decision.data.answers and the comment in agent_note.
pinrail ask [QUESTION] [OPTIONS]| Argument | Description |
|---|---|
<QUESTION> | The first question, as one line, which can use inline Markdown such as code for a command or a path. |
--ask <QUESTION> | Another question. The options after it, up to the next --ask, apply to it; those before it apply to the question before. Up to 10 questions in all. |
--choice <TEXT> | An answer the person can pick. Give it once for each choice, at least twice. A choice can contain spaces and commas. Without it, the person types the answer. |
--multiple <MULTIPLE> | With --choice: the person can pick more than one. |
--yes-no <YES_NO> | A question answered with yes or no. |
--recommend <CHOICE> | The choice you would make, shown as recommended: one of the choices, or yes or no. |
--context <MARKDOWN|-|@FILE> | More detail, shown below the question, as Markdown: given inline, as - for stdin, or as @FILE. |
--attach <PATH[=NAME]> | A file sent with the question it follows, listed under it: a screenshot, a chart or a log. Its context shows an image in place with |
--suggest-reply <TEXT> | The reply you expect, one line: the app shows it in the person’s empty reply box, and Tab accepts it. Such as “Yes, commit it and go on to PIN-55”. |
--title <TITLE> | The title the inbox shows [default: the question, and with several, the first and how many more]. |
--data <JSON|FILE|-> | The questions as JSON, given inline, as a file path, or as - for stdin, in place of the options above: {“questions”: [{“id”, “question”, “answer”, “choices”, “recommended”, “context”}]}, where answer is text, choice, choices or yes-no. |
--origin <ORIGIN> | Where the questions come from, as for submit. |
--requested-by <REQUESTED_BY> | Who is asking, as for submit. Env: PINRAIL_REQUESTED_BY. |
--timeout <TIMEOUT> | Stop waiting after this many seconds and exit with 4. 0 waits indefinitely. PINRAIL_TIMEOUT sets this for every wait. |
--item <ITEM> | The work item this is for, by its key or its number in the checkout. Repeat it for several [default: the item the session holds; a session holding several must name them, or pass --no-item]. |
--no-item | It is for none of the work items the session holds. |
--no-start | Do not start the server when it is not running. |
pinrail status
Section titled “pinrail status”Say what the agent is doing in its session, and receive the person’s messages.
A status is one line, shown in the session’s thread in the app.
pinrail status --start "Add rate limiting to the public API"pinrail status "Running the end-to-end suite"pinrail status --note --file summary.mdpinrail status --done "Pushed the fix"The app keeps every status, so the thread shows what the agent did between its questions and reviews. --start says the agent starts a new stage of work, and names it: the newest stage started is the session’s title in the app. --done says the agent has finished, and its text is then optional. A status after it says the agent is working again.
--note sends a note instead: a message in Markdown that tells the person something, such as a summary of a stage, and asks nothing. --attach sends files with it, as for submit. It shows in the thread and changes nothing else: it is not the latest status, and it neither starts nor ends a stage.
The person can send the agent messages from the thread. Each status prints the messages waiting for the agent, oldest first, and each message is printed once.
The command finds the agent and its session as submit does, and does not wait. It prints the stage the agent last reported, or that no stage is open, followed by any messages from the person.
pinrail status [TEXT] [OPTIONS]| Argument | Description |
|---|---|
<TEXT> | What the agent is doing, as one line of plain text of at most 200 characters. With --note, the note’s Markdown, or - to read it from stdin. |
--start | The agent starts a new stage of work, which the text names, and which names the session in the app. |
--done | The agent has finished its work in the session. |
--note | The text is a note: Markdown of at most 10,000 characters, on as many lines as it needs. |
--file <PATH> | With --note, read the note from this file. |
--attach <PATH[=NAME]> | With --note, a file the note carries, under its own name or NAME; the note shows an image it refers to as |
--origin <ORIGIN> | Where the agent works, as for submit. |
--requested-by <REQUESTED_BY> | Who is working, as for submit. Env: PINRAIL_REQUESTED_BY. |
--no-start | Do not start the server when it is not running. |
pinrail submit
Section titled “pinrail submit”Submit a review, and with --wait, wait for the decision and print it.
The options build the review: the plugin, --title, and the payload from --data. Alternatively, give the whole request as one JSON file with --request, in the form the API takes:
{ "plugin": "list", "title": "Sentry triage", "origin": {"repo": "acme"}, "payload": {"groups": []}}The keys are plugin, title, payload, origin, revises, expires_at and requested_by. Options override the file’s keys, and --data replaces its payload, so you can send a new round with the same file, --revises and the id of the earlier round. You can leave out the plugin argument when the file names one.
To send files with the payload, use --attach, for a plugin that accepts files (pinrail plugins shows which plugins do). The payload refers to each file as {“$attachment”: "
pinrail submit model --data models.json \ --attach out/pivot.glb --attach out/v2.glb=column.glbIn a --request file, list the files under “attachments”, such as {“pivot.glb”: “out/pivot.glb”}, with paths relative to the file. An entry can also be {“path”: …, “media_type”: …}, as in a plugin’s fixtures, so you can send a fixture unchanged. Pinrail checks the submission before it uploads anything, and it does not upload a file that the app already has.
pinrail submit [PLUGIN] [OPTIONS]| Argument | Description |
|---|---|
<PLUGIN> | The plugin that defines this kind of review, such as review. |
--title <TITLE> | The title the inbox shows for the review. |
--request <JSON|FILE|-> | The whole request as JSON, given inline, as a file path, or as - for stdin. Other options override its keys. |
--origin <ORIGIN> | Where the review comes from, as comma-separated key=value pairs. The keys are repo (the project, as owner/name), ref (a branch or pull request), workflow and run_id (what asked for the review), and url (a link back, which may contain commas). In a git checkout, repo defaults to the remote, and ref defaults to the branch when the repo is the checkout’s own. For example: repo=acme/api,ref=42,url=…. |
--data <JSON|FILE|-> | The payload as JSON, given inline, as a file path, or as - for stdin. |
--attach <PATH[=NAME]> | A file to send with the payload. The payload refers to it as {“$attachment”: " |
--revises <REVISES> | The id of the review that this one is a new round of. |
--expires-at <EXPIRES_AT> | The time after which the review expires, as an ISO 8601 timestamp. |
--requested-by <REQUESTED_BY> | Who is asking, shown on the review as its requester, with the agent’s icon when the app knows the agent [default: the coding agent the command runs under, detected from the variables it sets (claude-code, codex, cursor, antigravity, grok, opencode, pi, goose, amp, copilot, kiro, augment, cline, hermes-agent, kimi), or else pinrail-cli]. Env: PINRAIL_REQUESTED_BY. |
--sample <NAME> | Send one of the plugin’s sample reviews, which show what the plugin looks like, instead of a payload: the one named, or else its first. --title and --origin still apply. |
--wait | Wait until the review ends, whether or not it is decided (see wait). |
--dry-run | Run every check on the submission without creating a review. The command exits with 0 if the review would be accepted, and with 2 and the violations if not. |
--timeout <TIMEOUT> | With --wait, stop waiting after this many seconds and exit with 4. 0 waits indefinitely. PINRAIL_TIMEOUT sets this for every wait. |
--decision-out <FILE> | With --wait, also write decision.data to this file as JSON once the review is decided. pinrail show |
--item <ITEM> | The work item this is for, by its key or its number in the checkout. Repeat it for several [default: the item the session holds; a session holding several must name them, or pass --no-item]. |
--no-item | It is for none of the work items the session holds. |
--no-start | Do not start the server when it is not running. |
pinrail items
Section titled “pinrail items”Add, take, change and close work items: tasks recorded in Pinrail, with sub-items and dependencies.
A work item belongs to a repository, which numbers it under a prefix: its key, such as PIN-42. Inside the repository’s git checkout, the number alone names it too.
pinrail items next --claimpinrail items show PIN-42pinrail items done PIN-42 --comment "Loader in core/src/themes.rs"While a session holds items, the reviews and questions it sends belong to all of them, unless --item names the ones they are for.
pinrail items <COMMAND>pinrail items add
Section titled “pinrail items add”Add a work item, or a whole breakdown of them with --file.
An item belongs to the repository of the git checkout, or to the one --repo names. It prints the item’s key, such as PIN-42, which every other command takes, as does the number alone inside the checkout.
pinrail items add "Load themes in the core" \ --body "Read the theme files when the app starts." \ --parent PIN-40 --depends-on PIN-41A breakdown is a JSON file of items, each with a ref of its own that the others name it by, as a parent or in depends_on, before it has a key. Pinrail adds them all or none:
{"items": [ {"ref": "themes", "title": "Custom themes"}, {"ref": "format", "parent": "themes", "title": "Theme file format"}, {"ref": "load", "parent": "themes", "title": "Load themes", "depends_on": ["format", "PIN-38"]}]}pinrail items add [TITLE] [OPTIONS]| Argument | Description |
|---|---|
<TITLE> | The item’s title, one line. |
--body <BODY> | The description, in Markdown: the goal, the context and what done means. |
--body-file <FILE> | Read the description from a file, or from stdin with -. |
--parent <ITEM> | The item it is part of. |
--depends-on <ITEM> | Items that must be done first; several, or separated by commas. |
--link <URL> | A link, such as the issue elsewhere. |
--attach <PATH[=NAME]> | A file the description shows as attachment:NAME. |
--file <FILE> | A breakdown: a JSON file of items, or - for stdin. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items list
Section titled “pinrail items list”List the work items that are open, in progress or on hold.
pinrail items list [OPTIONS]| Argument | Description |
|---|---|
--ready | Only the items that are ready. |
--blocked | Only the items that wait for an item they depend on. |
--status <STATUS> | Only these: open, in_progress, on_hold, done, cancelled, ready or blocked, separated by commas. |
--parent <ITEM> | Only the sub-items of this item. |
--search <WORDS> | Words that must all be in the title or the description. |
--queued | Only the person’s queue, in its order: the items next offers first. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items next
Section titled “pinrail items next”Print the next work item that is ready, and claim it with --claim.
Ready means open, not on hold nor under an item on hold, waiting for no item it depends on, and with no open sub-item. The next is a sub-item of an item the session holds, if any, then the first ready item of the person’s queue, then the item that unblocks the most others, then the oldest. --claim takes it for this session: it is in progress, and the reviews and questions the session sends belong to it.
pinrail items next [OPTIONS]| Argument | Description |
|---|---|
--claim | Claim it for this session. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items show
Section titled “pinrail items show”Print a work item: its description, what it depends on and blocks, its sub-items, reviews, comments and sessions.
Its files, and those of its comments, are saved under their own names in a folder in the system’s temporary folder, and listed with their paths, so you can open them there.
pinrail items show <ITEM> [OPTIONS]| Argument | Description |
|---|---|
<ITEM> | The item: its key, such as PIN-42, or its number in the checkout. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items edit
Section titled “pinrail items edit”Change a work item: its title, description, status, claim, parent, dependencies, link, repository or files.
pinrail items edit <ITEM> [OPTIONS]| Argument | Description |
|---|---|
<ITEM> | The item: its key, such as PIN-42, or its number in the checkout. |
--title <TITLE> | |
--body <BODY> | The description, in Markdown, which replaces the one it has. |
--body-file <FILE> | Read the description from a file, or from stdin with -. |
--status <STATUS> | Open, in_progress, done or cancelled; an agent cancels with --comment. Only the person puts an item on hold (on_hold) or takes it off. |
--claim | Claim it for this session. |
--take | With --claim, take it from the session that holds it. |
--release | Give up this session’s claim: the item is open again. |
--parent <ITEM> | Put it under this item. |
--no-parent | Take it out from under its parent. |
--depends-on <ITEM> | Items it must wait for; several, or separated by commas. |
--no-depends-on <ITEM> | Items it no longer waits for. |
--link <URL> | |
--no-link | Remove its link. |
--move-to <REPO> | Move it to another repository, where it takes the next number; its old key still finds it. |
--attach <PATH[=NAME]> | A file the description shows as attachment:NAME. |
--detach <NAME> | Remove a file from the description, by name. |
--comment <COMMENT> | A comment that goes with the change. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items comment
Section titled “pinrail items comment”Comment on a work item.
pinrail items comment <ITEM> [TEXT] [OPTIONS]| Argument | Description |
|---|---|
<ITEM> | The item: its key, such as PIN-42, or its number in the checkout. |
<TEXT> | The comment, in Markdown. |
--file <FILE> | Read the comment from a file, or from stdin with -. |
--attach <PATH[=NAME]> | A file the comment shows as attachment:NAME. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail items done
Section titled “pinrail items done”Mark a work item done, with a comment that says what was done.
An agent can mark an item done only when no review or question of it waits on the person and its sub-items are done or cancelled; the command says what is still open otherwise, and exits with 2. It prints the items that are ready now.
pinrail items done <ITEM> [OPTIONS]| Argument | Description |
|---|---|
<ITEM> | The item: its key, such as PIN-42, or its number in the checkout. |
--comment <COMMENT> | What was done and where, for whoever continues from it. |
--repo <REPO> | The repository, outside its git checkout [default: the checkout’s]. |
--requested-by <REQUESTED_BY> | Who is working [default: the agent the command runs under]. Env: PINRAIL_REQUESTED_BY. |
pinrail wait
Section titled “pinrail wait”Wait until a review ends, then print its decision as Markdown, or the whole review as JSON with --json.
pinrail wait <ID> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
--timeout <TIMEOUT> | Stop waiting after this many seconds and exit with 4. 0 waits indefinitely. PINRAIL_TIMEOUT sets this for every wait. |
--decision-out <FILE> | Also write decision.data to this file as JSON once the review is decided. pinrail show |
pinrail show
Section titled “pinrail show”Print a review as Markdown, or the whole review as JSON with --json, including its payload and decision.
pinrail show <ID>| Argument | Description |
|---|---|
<ID> | The review’s id. |
pinrail rounds
Section titled “pinrail rounds”List every round of a review, oldest first, without payloads.
pinrail rounds <ID>| Argument | Description |
|---|---|
<ID> | The review’s id. |
pinrail events
Section titled “pinrail events”Print a review’s event log.
pinrail events <ID>| Argument | Description |
|---|---|
<ID> | The review’s id. |
pinrail list
Section titled “pinrail list”List reviews, newest first, without payloads.
By default, the command lists only pending reviews and, in a git checkout, only those of its project. The project is named the way submit names it: the remote’s owner/name, or the folder’s name when there is no remote. Outside a git checkout, the command lists the pending reviews of every project. Use --status and --repo to choose other reviews, and --all to list every review.
pinrail list [OPTIONS]| Argument | Description |
|---|---|
--status <STATUS> | The status to list: pending, decided, withdrawn, discarded or expired. Separate several with commas [default: pending, unless --all]. |
--repo <REPO> | The project, as the origin’s repo. Use - for reviews that name no project [default: the git checkout’s project, unless --all]. |
--workflow <WORKFLOW> | The workflow that asked for the review, as the origin’s workflow. |
--ref <REFERENCE> | The branch, pull request or other ref, as the origin’s ref. |
--run-id <RUN_ID> | The run that asked for the review, as the origin’s run_id. |
--plugin <PLUGIN> | List only reviews of this plugin. |
--search <WORDS> | Words that must all appear in the title, payload, plugin, requester, origin or the name of the person who decided. |
--cursor <CURSOR> | List only reviews older than this id. |
--limit <LIMIT> | The most reviews to list. Use --cursor to list the next page. |
--item <ITEM> | List only the reviews and questions of this work item, by its key. |
--all | List every review, of any status and project unless --status or --repo limits them, and every page unless --limit caps the number. |
--include-revised | Include rounds that a later round revises. |
pinrail decide
Section titled “pinrail decide”Record a decision from a test or a tool.
An agent never decides a review that it submitted. Only the person does. The app records that the decision was made with pinrail decide, by the agent the command runs under, if any, and in which agent session, and shows this with the decision.
pinrail decide <ID> --data <JSON|FILE|-> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
--data <JSON|FILE|-> | The decision as JSON, given inline, as a file path, or as - for stdin. Required. |
--note <NOTE> | A note to the agent that requested the review. |
pinrail withdraw
Section titled “pinrail withdraw”Withdraw a pending review. A command that is waiting on it exits with 3.
pinrail withdraw <ID> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
--reason <REASON> | Why the review is no longer needed. |
pinrail discard
Section titled “pinrail discard”Discard a pending review.
This does what discarding does in the app. A command that is waiting on the review exits with 5 and tells the agent to stop. An agent never discards a review that it submitted. The app records that the review was discarded with pinrail discard, as it does for pinrail decide.
pinrail discard <ID> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
--reason <REASON> | The reason, which the agent receives. |
--by <BY> | Who discards the review [default: the agent the command runs under, if any]. |
pinrail plugins
Section titled “pinrail plugins”List the installed plugins and when to use each one.
The listing includes each plugin’s install record and settings. pinrail plugins describe <name> shows one plugin in full.
pinrail plugins [COMMAND]pinrail plugins install
Section titled “pinrail plugins install”Install an official plugin by name, or a plugin from a folder or a zip.
An official plugin, such as list, is installed from the plugins the app carries, at the newest version it has. A name is taken as a folder when a folder of that name exists here. Installing again, from the same place or another, replaces the installed plugin: this is how a plugin is upgraded.
pinrail plugins install <SOURCE> [OPTIONS]| Argument | Description |
|---|---|
<SOURCE> | An official plugin’s name, such as list, or a plugin’s folder, or a zip of it. |
--link | Serve the folder directly instead of copying it, while you develop the plugin. |
--allow-skill | Let the plugin’s skill reach your connected agents. Without it, the skill waits until you turn it on in Settings › Plugins in the app. |
pinrail plugins remove
Section titled “pinrail plugins remove”Remove an installed plugin. The versions that existing reviews render with are kept.
pinrail plugins remove <NAME>| Argument | Description |
|---|---|
<NAME> | The plugin’s name. |
pinrail plugins skill
Section titled “pinrail plugins skill”Print a plugin’s skill: how to build a payload for it.
A plugin can ship a skill for the agents that ask with it, such as how to derive its payload from the work. This prints its SKILL.md, or another file of the skill that SKILL.md names, such as a reference. pinrail plugins says which plugins have one. A copied plugin’s skill is printed once the person allowed it.
pinrail plugins skill <NAME> [FILE]| Argument | Description |
|---|---|
<NAME> | The plugin’s name. |
<FILE> | A file of the skill, such as references/payload.md; SKILL.md when none is given. |
pinrail plugins describe
Section titled “pinrail plugins describe”Show what an agent needs to submit a review with a plugin.
The description includes the payload schema, an example payload and the files the plugin accepts. With --json, it also includes the decision schema. pinrail plugins lists the plugins and says when to use each one.
pinrail plugins describe <NAME> [OPTIONS]| Argument | Description |
|---|---|
<NAME> | The plugin’s name. |
--payload-schema | Print only the payload’s JSON schema, for a tool that checks or builds payloads. |
--example | Print only the example payload, as a starting point for your own. |
--decision-schema | Print only the decision’s JSON schema, which describes decision.data, for processing the decision with --json. Without --json, the decision is printed as Markdown. |
pinrail plugins new
Section titled “pinrail plugins new”Create a new plugin.
The new folder contains a manifest, schemas, a sample review, a view, and the SDK’s types. The plain template’s view needs no build. The typescript template, or ts, and the react template write the view in src/, which npm run build turns into view/. --playwright adds a first test of the view, run with Playwright under the SDK’s harness. --link installs the plugin as a link right away, which needs a view, so it takes the plain template only.
pinrail plugins new <NAME> [OPTIONS]| Argument | Description |
|---|---|
<NAME> | The plugin’s name, which starts with a lowercase letter followed by letters, digits, _ or -. |
--dir <DIR> | The folder to write the plugin to [default: ./ |
--template <TEMPLATE> | How the view is written. One of plain, typescript, react. Default: plain. |
--playwright | Add a first test of the view, with package.json and Playwright’s configuration. |
--link | Install the plugin as a link after writing it, so the app serves the folder directly. |
pinrail plugins schema
Section titled “pinrail plugins schema”Print one of the plugin SDK’s JSON Schemas.
The manifest’s schema, which every plugin’s manifest.json is checked against, or the attachment schema, which a payload schema copies to describe a field that names an attached file. They are the schemas this command was built with, and need no app.
pinrail plugins schema [WHICH]| Argument | Description |
|---|---|
<WHICH> | Which schema to print. One of manifest, attachment. Default: manifest. |
pinrail plugins check
Section titled “pinrail plugins check”Check a plugin folder without installing it.
The command reports why the app would refuse the folder, and each feature the app would drop. It also checks the plugin’s recorded decisions, fixtures/
pinrail plugins check [DIR] [OPTIONS]| Argument | Description |
|---|---|
<DIR> | The plugin’s folder. Default: .. |
--since <DIR> | The release before this one, as a folder: also report what this release’s schemas no longer accept of what that one took, which semantic versioning allows only in a version that announces it. |
--update-fixtures | Write each recorded decision’s |
pinrail attachments
Section titled “pinrail attachments”List the files a review carries, or save one of them.
pinrail attachments <COMMAND>pinrail attachments list
Section titled “pinrail attachments list”List the files a review carries, with their names, sizes, media types and hashes.
pinrail attachments list <ID>| Argument | Description |
|---|---|
<ID> | The review’s id. |
pinrail attachments get
Section titled “pinrail attachments get”Save a file that a review carries.
pinrail attachments get <ID> <NAME> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
<NAME> | The file’s name on the review. |
--output <PATH|-> | The path to write the file to, or - for stdout [default: the file’s name, in the current directory]. |
--force | Replace an existing file. |
pinrail export
Section titled “pinrail export”Write every review as a JSON file in a directory.
pinrail export <DIR>| Argument | Description |
|---|---|
<DIR> | The directory to write to. It is created if it does not exist. |
pinrail serve
Section titled “pinrail serve”Start the server if it is not running, and print its URL.
pinrail servepinrail docs
Section titled “pinrail docs”Print the briefs on using Pinrail as an agent.
Without a path, the command prints the main brief, which is Pinrail’s agent skill, and a menu of the other briefs. With a path, such as pinrail docs building, it prints that brief.
pinrail docs [PATH] [OPTIONS]| Argument | Description |
|---|---|
<PATH> | The brief to print, as the menu names it [default: the main brief]. |
--tree | Print the path and subject of every brief, as a tree. |
pinrail open
Section titled “pinrail open”Open a review in the app, or its preview in a browser with --browser.
The command opens the link pinrail://reviews/
--browser opens
pinrail open <ID> [OPTIONS]| Argument | Description |
|---|---|
<ID> | The review’s id. |
--browser | Open the preview in the default browser, to try a view while building a plugin. |
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 | Done. For wait and submit --wait, the review was decided. |
1 | Error: bad arguments, the app could not be reached, a file could not be read or written, or the app failed on its side. wait and submit --wait keep waiting through an error inside the app until it answers again. |
2 | The app refused the request, for example a payload the plugin’s schema rejects, or a folder that plugins check would not install. Why is on stderr. |
3 | The review was withdrawn by the agent, or expired, before anyone decided. |
4 | --timeout ran out. The review is still pending. |
5 | The person discarded the review: stop the work it was gating, and do not ask again. |
Environment
Section titled “Environment”| Variable | Used for |
|---|---|
PINRAIL_DATA_DIR | Where the running server’s server.json is, to find it; also where a server the CLI starts keeps its data. |
PINRAIL_JSON | --json. Print JSON instead of Markdown, for a script or tool that processes the result. PINRAIL_JSON=1 sets this for a whole session. |
PINRAIL_PORT | The port to try when no server advertises itself. Defaults to 4747. |
PINRAIL_REQUESTED_BY | --requested-by <REQUESTED_BY>. Who is asking, as for submit. |
PINRAIL_SERVER_CMD | How to start a server when none is running, run through sh -c, or cmd /C on Windows. submit, serve, plugins, plugins describe, plugins check and plugins new --link use it. |
PINRAIL_TIMEOUT | How many seconds wait and submit --wait wait before they give up with exit 4, when --timeout is not given. Unset or 0 waits without a limit. |
PINRAIL_URL | --url <URL>. The server’s URL [default: PINRAIL_URL, then the address in the running server’s server.json, then http://127.0.0.1:4747]. |
PINRAIL_VERBOSE | --verbose. Also report each step on stderr, such as the origin read from git, the server started, the files uploaded and where files were written. |