This guide is for developers who use the shipvo command. It lists each command with an example and the output to expect, and ends with fixes for errors people have hit. If you are new to the terminal, start with Create your first app instead.
Run npx -y @shipvo/cli --help to see the commands your installed version has.
shipvo init
Two modes.
shipvo init <dir>creates a new app in<dir>. See Getting started.shipvo init(orshipvo init .) inside an existing Expo or bare React Native app switches to adopt mode.
Adopt mode
Run it in the app's root. The folder needs a package.json with expo and an app.json or app.config.js/ts.
npx -y @shipvo/cli init --dry-run # print the plan, change nothing
npx -y @shipvo/cli init # print the plan, then ask
npx -y @shipvo/cli init --yes # apply without askingIt detects the Expo SDK version, the package manager (from the lockfile: npm, pnpm, yarn or bun), the config kind, and whether expo-updates or CodePush is present. Then it plans:
- install
@shipvo/runtime(and@shipvo/devicewith--device) with your package manager, and@shipvo/cliand@shipvo/simas dev dependencies, soshipvoin your scripts and CI is ours and not another npm package; - add the
@shipvo/runtimeconfig plugin toapp.json, with a new signing key in.shipvo/seed.txt(git-ignored), or the key you pass with--public-key; - write
shipvo.json(the app id comes from the slug), and addsim,publishandrollbackscripts; - add
.shipvo/to.gitignore; - add
.github/workflows/publish.ymlonly if it does not exist. It runs by hand only (workflow_dispatch) and skips pushes whose commit message has[no-ota]. It does not publish on every push tomain, so nothing ships to phones by surprise. Add apushtrigger with apathsfilter when you want that.
With app.config.js or app.config.ts it does not rewrite your code. It prints the exact lines to add to plugins.
Rules it keeps:
- It never overwrites a file. In an Expo app it never touches
ios/orandroid/. - Running it again changes nothing.
- It refuses apps that use
expo-updatesorreact-native-code-push, because two update systems would fight over the bundle. Forexpo-updates, runshipvo migrate --planand see Migrate from EAS Update. For CodePush, see Migrate from CodePush. - A bare React Native app (committed
ios/andandroid/, no config plugins) is handled as described below. If your app is managed, add any config plugin toapp.json, or remove theios/andandroid/folders, and run it again.
When it finishes it runs shipvo doctor, then tells you to rebuild the native app once and run shipvo publish --dry-run.
Bare React Native apps
In a bare app, shipvo init uses the same plan, --dry-run and confirmation. The plan has these extra steps, each listed only if it is needed:
- run
npx install-expo-modules@latest, if Expo Modules are not set up yet. It runs only after you confirm or pass--yes; - add or update the
dev.shipvo.*meta-data inandroid/app/src/main/AndroidManifest.xml; - add or update the
Shipvo*keys inios/<app>/Info.plist.
The values are the same ones the config plugin writes. Other keys keep their order, and a second run changes nothing. It does not add a config plugin, because a bare app has no prebuild. If it cannot find the manifest or the Info.plist, it stops and changes nothing. Then it prints the next steps: cd ios && pod install, rebuild both apps, shipvo publish --dry-run.
On iOS, shipvo init accepts the Expo setup in either AppDelegate or SceneDelegate, so apps on the UIScene lifecycle are recognised.
Other options: --control-plane <url>. --public-key <key> must be base64 that decodes to 32 bytes, or it exits 2 before changing anything. If shipvo.json has a publicKey that does not match .shipvo/seed.txt, it stops and changes nothing. If app.json is not valid JSON, it stops with a one-line message. If a step fails, it lists the steps already applied.
shipvo preview
Publishes a web preview of your app that anyone can open in a browser or on a phone, with no install, no account and no control plane. It uses here.now.
shipvo preview # build, publish, print the link
shipvo preview --json # one JSON line for agents: url, claimUrl, expiresAt, files, warningsWhat it does:
- Builds the web app with the simulated device (
PN_SIM=1 npx expo export --platform web) into.shipvo/preview-build. - Wraps it in a frame page (
index.html) with a phone, iPhone-size and tablet switcher and a light and dark switch. Your app's own page is served asapp.htmlinside the frame. On a phone-width screen the app fills the screen. - Publishes anonymously: create, upload, finalize. Expired upload URLs are refreshed. A 429 from here.now is retried after
retry_afterseconds. Warnings from here.now are printed.
The link is public and expires in 24 hours. Anyone with the link can open it. To keep it, open the claim link and sign in to here.now. The claim link is shown once; copy it as printed.
Safety rules:
- It never uploads
.shipvo/,.env*, key files (.pem,.key,.p8,.p12,.jks,.mobileprovision),seed.txt,publish-tokenor source maps. - It refuses to publish if a text file in the build holds a private key, your signing seed or publish token, or another known secret pattern. The message names the file, never the value.
Options: --skip-build publishes the last build in .shipvo/preview-build.
shipvo.json has a preview setting: "here.now" (default). "control-plane" (permanent hosting at /w/{app}/r{release}/) is reserved and not built yet; setting it stops with a message.
Testers can tap Comment (a button that stays visible on phones), tap a point in the app and type a note. Each note stores the text, the point, the screen and the steps taken so far. Notes show in a side list, stay in the browser (localStorage) until exported, and Export comments.json downloads them. Nothing is uploaded. The point is measured from the top left of the whole device box, status bar included. Steps are kept in memory, so notes saved after a reload start with an empty step list.
Agents can call the MCP tool publish_preview; it runs shipvo preview --json in PN_APP_DIR (or the current folder) and returns { url, claimUrl, expiresAt }.
A preview can take longer than some clients wait for one tool call. publish_preview (and upload_build) take an optional wait_ms (default 20000). They wait up to that long and return the result, or { status: "running", job }. Call job_status { job, wait_ms? } to read it: it returns running, done with the result, or failed with a typed error { code, error }, and with wait_ms it waits for the job to finish. Calling the tool again while the job runs returns the same job, so a retry never starts a second publish. Jobs belong to the key that started them and are kept for 15 minutes after they finish.
shipvo init adds .github/workflows/preview.yml, which publishes each pull request's web build and comments the link on the pull request. Pull requests from forks are skipped.
Device panel
The preview page has a Device panel beside the phone (under it at phone width). It sets the same simulated device state as the MCP set_device and push_notification tools. Every event is simulated.
- Location: pick a place, or type latitude and longitude.
- Camera: put an EAN-13 or QR code in front of the camera, or nothing. Images are left for later.
- Fingerprint / Face ID: matches or does not match every check until you change it.
- Payment: every payment is approved or declined until you change it.
- Network: online, slow (the app's
fetchcalls wait 1.5 s) or offline. - Push notification: send a title and body; it shows as a banner. Nothing is delivered if the app has not been granted notification permission, and the panel says so.
policy in shipvo.json
An optional policy section writes release rules down. shipvo publish --dry-run checks them. If a rule refuses, it prints the rule and the reason and exits with code 1. The control plane checks the same rules on the real publish, including shipvo promote. It refuses with 403 policy_refused, the rule and the reason, and writes one audit row.
{
"appId": "habits",
"policy": {
"maxBand": "b1",
"agentMaxBand": "b0",
"blockedWeekdays": ["fri"],
"blockedAfterHour": 12
}
}Then run:
shipvo publish --dry-run --bands b0,b1,b2
# Refused by policy rule maxBand: this publish reaches b2, but policy.maxBand is b1To check the policy without building anything, use --dry-run-policy. It reads shipvo.json, checks the bands in --bands (default all three), prints the result and publishes nothing. It exits 0 when the policy allows the publish or there is no policy, and 1 when a rule refuses.
shipvo publish --dry-run-policy --bands b0,b1,b2| Field | Meaning |
|---|---|
maxBand | Widest band any publish may reach: b0, b1 or b2. The widest band in --bands counts. |
agentMaxBand | Same, for a publish run by an agent. Set SHIPVO_ACTOR=agent in the agent's environment. Without it the publish counts as human. |
blockedWeekdays | Days with no publish: mon to sun, in the policy's time zone (see timeZone). |
timeZone | IANA name such as Europe/Paris. Sets the zone for blockedWeekdays and blockedAfterHour. Without it the CLI uses the machine's local time and the control plane uses UTC. |
blockedAfterHour | Hour 0-23, local time. Publishes on blockedWeekdays are refused from this hour on (12 means from 12:00). Without it, the whole day is blocked. Needs blockedWeekdays. |
Without a policy section nothing is checked. A bad section (unknown field, wrong value) stops the dry run and names the field, for example policy.maxBand.
shipvo auto-halt
Stops serving a release on its own when too many devices fail to apply it.
shipvo auto-halt # print the current setting
shipvo auto-halt --threshold 0.2 --min-reports 20 # on: halt when more than 20% of at least 20 reports failed
shipvo auto-halt --off # off
shipvo auto-halt --threshold 0.2 --dry-run # print the change, write nothing--thresholdis above 0 and at most 1.--min-reportsis a whole number from 1 to 10000 (default 20).- It needs
SHIPVO_OWNER_TOKEN, or the publish token fromshipvo app create(SHIPVO_PUBLISH_TOKENor.shipvo/publish-token). A publish token can turn auto-halt off, so a leaked CI publish token can disable it. shipvo statusshows the setting:auto-halt: offorauto-halt: on at 20% after 20 reports.- The route behind it is
GET,PUTandDELETEon/app/<app>/api/halt-config.PUTtakesthresholdand optionalmin_reportsandmin_installs; leaving outmin_installskeeps the stored value.GETreturns all three. A bad value is a 400 witherror: "bad_halt_config".
shipvo agents setup
Sets a project up for AI coding agents.
shipvo agents setup # write the files
shipvo agents setup --for cursor,codex # also write these agents, detected or not
shipvo agents setup --all # treat every agent as present
shipvo agents setup --global # also write user-level files (Codex CLI, Windsurf)
shipvo agents setup --dry-run # show what would change, write nothing
shipvo agents setup --json # machine-readable result- It detects the project: Shipvo app (
shipvo.json), Capacitor, Expo, bare React Native. - It writes a section to
AGENTS.mdbetween<!-- shipvo:begin -->and<!-- shipvo:end -->. A missing file is created. Text outside the markers is never changed. - It adds
@shipvo/mcpto devDependencies with your package manager (npm, pnpm, yarn or bun) if it is missing, then adds theshipvoserver (node node_modules/@shipvo/mcp/dist/server.js, withPN_SIMset to your sim port) to the MCP config of each coding agent it detects in the project (a folder, a file or the CLI onPATH)..mcp.jsonfor Claude Code is always written. Other servers and keys stay. A file that is not valid JSON is left alone and the command exits 2. --hostedwrites the hosted Shipvo phone instead: the remote URL plus anAuthorizationheader for each agent, and the key-in-path URL for Claude Desktop and ChatGPT. It runsshipvo loginfirst if there is no key. Project files that git tracks or does not ignore are not written; the block is printed with the reason. Printed output shows<your Shipvo key>, never the key.--npxwrites a pinnednpx -y @shipvo/mcp@<installed version>entry instead and installs nothing.- Agents it does not detect are listed with their
--forname.--for <names>takes a comma-separated list of ids and writes those agents;--alltreats every agent as present. - Agent ids:
claude,cursor,vscode,gemini,qwen,roo,kiro,opencode,codex,windsurf,claude-desktop,cline,zed,goose,continue,amp. - Project files:
.mcp.json(Claude Code),.cursor/mcp.json,.vscode/mcp.json(VS Code and GitHub Copilot),.gemini/settings.json,.qwen/settings.json,.roo/mcp.json,.kiro/settings/mcp.json,opencode.json. - Codex CLI (
~/.codex/config.toml, other tables are kept) and Windsurf (~/.codeium/windsurf/mcp_config.json) are user-level files. They are written only with--global; without it the block is printed. - Claude Desktop, Cline, Zed, Goose, Continue and Amp print a block to paste, with the file it goes in.
--jsonaddsagents: one entry per agent with itsagentid,name,file,actionand, for printed blocks, theblock.- It prints the skill install line.
- Running it again changes nothing.
shipvo session
Open any Expo app on a headless Shipvo Phone and drive it from the shell, on Android and iOS. It needs no shipvo.json.
shipvo session start [android|ios] [--device "<model>"] [--name <n>] [--max-duration-minutes 30] [--port <n>] [--skip-build] [--json]
shipvo session devices
shipvo session screen | tap <ref> | type <ref> <text> | scroll <up|down|left|right> [<ref>] | back
shipvo session screenshot [--out <file>] [--no-frame]
shipvo session record start | record stop [--out <file>]
shipvo session errors
shipvo session start --a2ui <file> [--device "<model>"]
shipvo session a2ui send <file> | a2ui actions [--since <n>]
shipvo session get | list | stop | cleanCommands after start act on the newest running session; --id <id> names one. The session stops on its own after --max-duration-minutes. Screenshots and recordings show the phone in its Android or iPhone frame with the status bar. --a2ui opens A2UI messages on the phone with no app folder: see A2UI on Shipvo Phone. Steps, JSON fields and error codes: Test any Expo app from the terminal.
shipvo smoke
Does the app load? Run it after a change, with no test to write.
shipvo smoke [android|ios] [--timeout 30] [--json]It starts the simulator the way shipvo sim does, opens the app headless and waits for the first screen to settle. It fails when the page throws an error, has an unhandled promise rejection, or the first screen has no elements in the tree. It prints the time to the first screen, the element count and the first 5 errors. The optional android or ios (default android) is sent to the simulator as the session's device platform, so the app sees that platform and the phone dialogs use its wording. Any other value is a setup error (exit 2).
With --json it prints the envelope of shipvo status --json:
{ "ok": true, "code": "ok", "summary": "The app loads on android: first screen in 1945 ms, 30 elements, no errors",
"data": { "platform": "android", "time_to_first_screen_ms": 1945, "elements": 30, "errors": [], "error_count": 0 },
"next": [{ "command": "shipvo test --json", "why": "Run your step files." }] }data.errorsholds the first 5 error messages.error_countis the full count.codeis one ofok,errors,empty_screen,timeout(exit 1) orsetup_error(exit 2).- A missing browser or Playwright is a setup error.
nextthen holds the install command.
| Exit code | Meaning |
|---|---|
| 0 | The app loads |
| 1 | It threw, showed no elements, or did not show a first screen before --timeout seconds |
| 2 | Setup error: no shipvo.json, no browser, a bad flag |
Console messages are not checked, only thrown errors and unhandled rejections.
shipvo status --json
The agent's "what next" command. It prints one JSON line:
{ "ok": true, "code": "ok", "summary": "...",
"data": { "project": {}, "sim": {}, "run_server": {}, "signing_key": {}, "pending_release": {}, "store_step": {} },
"next": [{ "command": "shipvo sim", "why": "..." }] }data.project:{ kind, app_id }.sim: is something on port 4545.run_server: isshipvo runup (from.shipvo/run.json).signing_key.present: a seed in the environment or.shipvo/seed.txt.pending_release:{ newest, halted, auto_halt }.store_step: the next open step ofstore-plan.json, ornull.codeis one ofok,no_release,no_project,no_signing_key,release_halted,error.nextlists commands to run, most urgent first.- Without
--jsonthe output is the same table as before.
| Exit code | Meaning |
|---|---|
| 0 | ok: nothing needs doing (next may still have optional steps) |
| 1 | action needed: no project, no signing key, or a halted release |
| 2 | error: shipvo.json is invalid or the control plane could not be reached |
shipvo approvals
With policy.requireApprovalAbove set, a promote above that band waits for a second owner. These commands show and release the holds.
shipvo approvals list # hold id, release, band, proposer, age
shipvo approvals approve <id> # let the promote go through
shipvo approvals list --json # one JSON line: { ok, code, summary, data, next }; the list is data.approvalsapproveneeds a signed-in person (shipvo login) when an agent proposed the hold, which is the usual case: a promote made with the publish token.SHIPVO_OWNER_TOKENcounts as an agent, so it can approve only holds that a person proposed. With the env token on an agent's hold, the CLI printsRefused by rule self_approvalwith a hint to runshipvo login, and exits 1.listalso works with the publish token.- The proposer cannot approve its own hold, and an agent cannot approve an agent's hold. The second rule changes the existing approve endpoint: before,
OWNER_TOKENcould approve a hold made with the publish token. A setup with no signed-in person can no longer release an agent's hold. The CLI prints the rule (self_approval), exits 1, and the control plane writes an audit row for the refusal. - Exit codes: 0 done, 1 refused by a rule, 2 error. With
--jsonthe output is the same{ ok, code, summary, data, next }envelope asstatus --json. On a refusalcodeis the rule (self_approval) anddata.rulerepeats it; other failures useusage,config,no_credentials,unreachableorhttp_<status>. - MCP tools:
approvals_list(app)andapproval_approve(app, id). Both use the server's owner token (the MCP server holds no publish token), so an MCP agent counts as an agent and can approve only holds that a person proposed.
shipvo explore --flows
shipvo explore --flows also looks for sign up, log in, search, add to cart and checkout. It drives each with valid input and then invalid input, and writes explore-report-flows.md and explore-report-flows.json. Each flow is passed, failed (with the step) or not found. Pass a list to run some: --flows search,add-to-cart. A failed flow counts as a finding for --fail-on-findings; a flow that is not found does not. With --json, data.flows lists each flow with status, invalid_status and message, and report_files includes the two -flows files. When the walk has no findings and a flow failed, code is flows_failed.
shipvo explore --record-features <file>
Writes one JSON line per action with screen features, action features and the outcome. It holds roles, counts, types and hashes, never app text or typed values. Off by default. The line format is in explore-features.md.
--json for doctor, test and explore
shipvo doctor --json, shipvo test --json and shipvo explore --json print the same envelope as status --json: { ok, code, summary, data, next }. Stdout holds only that one JSON line. Progress and logs go to stderr, including the Playwright install notice for explore and the progress lines of test. The text output is unchanged without --json.
| Command | code values | data |
|---|---|---|
doctor | ok, checks_failed, usage | checks: [{ name, ok, fix, note }] |
test | ok, tests_failed, usage, error | flows, failed, repaired, unresolved |
explore | ok, findings, flows_failed, walk_failed, error | findings, flows, steps, screens, report_files, stopped_early |
next has one to three commands. A failed doctor check adds one entry that names the fix.
| Exit code | Meaning |
|---|---|
| 0 | ok |
| 1 | the check or test failed (explore exits 1 on findings or a failed --flows flow only with --fail-on-findings, and always when the walk fails) |
| 2 | usage or setup error |
shipvo sim --hosted
Builds the app the way shipvo sim does, uploads it for your SHIPVO_API_KEY and prints the id. Open it on the hosted phone as open_app("<app>@build:<id>"). --skip-build uploads the existing sim-dist. Errors and the assistant tool upload_build are in Test your build.
shipvo audit
For owners and teams who need a record of what happened to an app's releases. It exports the audit log, newest first, to stdout, so you can hand the file to an auditor. The log shows publishes, rollbacks, halts and key rotations.
shipvo audit shop > audit.json # JSON (default)
shipvo audit shop --format csv > audit.csv # CSV
shipvo audit shop --limit 100 # only the newest 100 entries- It pages through
GET /audit/<app>with?before=<id>, 200 rows at a time.--limitcaps the total (default: all). - Key rotations appear in the log as rows with
actionkey-rotation, merged by time with publishes and rollbacks.release,release_idandbeforeare empty;afterholds{ "sequence": n, "valid_from": "<ISO time>" }. They are merged into the first page, which holds the newest rows (up to 200), so an export includes rotations that fall within the newest 200 rows. See Key rotation. - CSV has a header row, every field in double quotes, and columns in this order:
id,app_id,at,actor,actor_kind,action,release,release_id,before,after. Objects are written as JSON text. - A value that starts with
=,+,-or@gets a leading'so a spreadsheet does not run it as a formula. - It needs
SHIPVO_OWNER_TOKEN, or the publish token fromshipvo app create. A non-2xx answer prints the status and exits 1. The token is never printed. - Key rotations (
shipvo keys rotate) appear in the log as rows withactionkey-rotation, next to publishes and rollbacks. Theirafteris{"sequence":n,"valid_from":"..."}, andrelease,release_idandbeforeare empty. Rows from both sources are merged by time. Rotation rows come only with the first page ofGET /audit/<app>(the request with nobefore).
What a row looks like when you rotate the release key (see Key rotation):
{ "action": "key-rotation", "release": null, "release_id": null, "before": null, "after": "{\"sequence\":2,\"valid_from\":\"2026-11-10T09:00:00.000Z\"}" }actionis one ofpublish,rollback,haltorkey-rotation. Akey-rotationrow has the key sequence number and the time it takes effect inafter;release,release_idandbeforearenull.- Rotation rows are merged with the other rows by time. They come with the first page only (the page without
before), soshipvo auditmerges them into the newest entries (cut to--limit), and a hand-made call toGET /audit/<app>?before=<id>does not.
shipvo run
shipvo run android or shipvo run ios builds the web export with the simulated device (the same build as shipvo sim), serves it on a local port and opens your default browser at a phone frame page. It does not use Playwright.
- Android frame: 412x915, status bar, punch-hole camera, gesture bar. A "Show Android system sheet" button (or a
postMessageof{ type: "shipvo:system-sheet" }from the app,open: falseto close) opens an overlay with Android permission wording. - iOS frame: 393x852, Dynamic Island, home indicator. A "Show iOS system sheet" button or the same
postMessageopens an overlay with iOS permission wording. - Reloading on a client-side route under
/app/(no file extension) serves the app shell. - The page shows a "Simulated" label and scales the phone to fit the window.
--no-openprints the URL and does not open a browser.--port <n>picks the port (default: any free port).--nativerunsnpx expo run:androidornpx expo run:iosinstead and says so.- If the app cannot build for web, the command exits with code 1 and names the module or file that failed.
- Ctrl+C stops the server.
shipvo promote
Widens a staged release to more bands. It reads a test report and refuses to widen a release whose flows failed.
shipvo test flows/ --release 3 --report shipvo-test-report.json
shipvo promote # reads shipvo-test-report.json if it exists
shipvo promote --report out/report.json
shipvo promote --force # promote anyway; prints that it overrode a failing report- A report whose
releasematches the release being promoted and has any failed flow stops promote with a non-zero exit. The message lists the failing flows.--dry-runstops the same way. - A report for a different release is stale. Promote prints a warning and goes on.
- With no report file, promote behaves as before.
First run of the simulator
shipvo sim, shipvo explore, shipvo test and shipvo store screenshots check the browser setup before they start:
- If
playwrightis not installed, the CLI installs it as a dev dependency with your package manager (pnpm, yarn, bun or npm, chosen from the lockfile). - The simulator uses system Chrome or Edge when it finds one. Otherwise it uses Playwright's Chromium, and downloads it once with
npx playwright install chromiumif it is missing.
shipvo doctor shows which browser it found. With no Chrome, Edge or Chromium it still passes, and notes that the first run downloads Chromium once.
Set SHIPVO_NO_AUTO_INSTALL=1 to turn both installs off. The command then stops and prints what to run yourself, and shipvo doctor fails the browser check when nothing is installed.
Troubleshooting
These come from fixed issues in this repository.
Executable doesn't exist when you run shipvo sim or shipvo doctor. The simulator's browser is not installed. Run npx playwright install chromium in the app folder. On Linux, add the system packages the message names.
ERR_PNPM_NO_MATCHING_VERSION for playwright after shipvo init. Apps made by an old CLI had a Playwright range that the registry could not satisfy. Update the CLI. New apps pin playwright to >=1.63.0 <1.65.0.
shipvo publish fails with ECONNRESET or a similar network error. The CLI shows the real error and the key it was writing, and retries network failures twice. If it still fails, check your connection and the control plane address. HTTP errors such as 401 are not retried: check your token.
shipvo publish says Refused by policy rule ... (also on --dry-run). Your policy section in shipvo.json forbids this publish. Change the cohort bands you publish to, or change the rule. Use --dry-run-policy to test the rule without building.
shipvo audit exits 1 with a status code. The token is missing or wrong. Set SHIPVO_OWNER_TOKEN, or use the publish token from shipvo app create.
shipvo sim --hosted says no_api_key. Set SHIPVO_API_KEY to your key (run shipvo login to get one, then shipvo mcp prints your config with the key in it). Then see Test your build.
shipvo sim --watch prints one line about a broken JSON file. Fix the comma or quote it names and save. Add --verbose for the full build error.
Next steps
- Test your app in CI, including
shipvo test --repairand--report. - Store details and screenshots.
- Self-host the control plane.
- Rollbacks and stored data:
stateVersionand--allow-state-downgrade. - Glossary for the words used here.
--json for publish, promote, rollback and auto-halt
These four commands take --json and print the same { ok, code, summary, data, next } envelope. Stdout holds only that one JSON line. Text, build output and the old summary go to stderr. Without --json nothing changes. Exit codes: 0 ok, 1 failed (including an unreachable or refusing control plane, a missing bundle, a policy refusal), 2 usage error (unknown flag, bad value, missing --to).
| Command | code on success | data |
|---|---|---|
publish | published | { app, release, bands, min_shell_version, bytes, patches, platforms, total_bytes, web? } (with --platform all, android and ios hold { bytes, patches } instead of bytes and patches) |
publish --dry-run | dry_run | the same, plus dry_run: true, out |
publish --dry-run-policy | policy_ok | { policy: "none" or "allowed", bands } |
promote | promoted, nothing_to_promote | { dry_run, promoted: [{ platform, release, from, bands, skipped_newer: [{ band, release }] }] } |
promote --dry-run | dry_run | the same with dry_run: true |
rollback | rolled_back | { app, rolled_back_to_code_of, new_release, min_shell_version, issued_at, platforms, bands, dry_run: false } |
rollback --dry-run | dry_run | the same with dry_run: true |
auto-halt | auto_halt_show, auto_halt_on, auto_halt_off, dry_run | { enabled, threshold, min_reports, dry_run, changed } (threshold and min_reports are null when off) |
Failure codes: usage, failed, policy_refused, no_bundle, not_found, no_pointer, tests_failed, blocked, report_unreadable, no_credentials, auth_failed, remote_failed, state_downgrade (see Rollbacks and stored data). On failure data is {} and summary is the error message.
Without --json, publish and rollback print a single plain sentence.
next suggests the follow-up. After publish it is shipvo status --json (and shipvo promote --to ... when some bands are left). After a dry run it is the real command. After a failure it is the likely fix, for example shipvo doctor --json.
--json for init, login, audit and keys
These commands take --json and print the same { ok, code, summary, data, next } envelope as the other --json commands. Stdout holds one JSON line. Progress and text go to stderr. Exit codes: 0 ok, 1 failed, 2 usage error. No envelope holds a key seed, a token or an API key.
| Command | code on success | data |
|---|---|---|
init <dir> | created | { mode: "create", dry_run, dir, app_id, control_plane, public_key, seed_file } (seed_file is the path of the git-ignored seed file, or null when you passed --public-key) |
init in an existing app | adopted, dry_run | the same with mode: "adopt". Needs --yes or --dry-run. |
login | signed_in | { login, key_prefix, saved_to, quota_minutes, expires_at, apps, mcp_url, device: { verification_uri, user_code } } |
audit <app> | ok | { app, count, rows } (--format csv is not combined with --json) |
keys | ok | { login, prefix, scope, app, expires_at, used_minutes, quota_minutes, last_used_at, mcp_url } |
keys export --out <file> | exported | { app_id, public_key, out }. --out is required, so the seed is never printed. |
keys import | imported, unchanged | { app_id, public_key, seed_file, gitignore_warning } |
keys root --out <file> | root_created | { public_key, file }. The seed goes to the file only. See Key rotation. |
keys rotate sign | rotation_signed | { app_id, envelope: { body, signature } } |
keys rotate upload | rotation_uploaded | { app_id, response } |
login --json writes the device URL and code to stderr as soon as it has them, so a person can open the page. It then waits for GitHub as it does without --json, and the final envelope repeats both in data.device.
Failure codes: usage, failed, dir_exists, init_failed, login_unavailable, login_failed, login_expired, login_timeout, no_credentials, auth_failed, remote_failed, no_project, not_signed_in, key_expired, key_invalid, no_seed, seed_mismatch, invalid_seed, rotate_failed, refused. On failure data is {} and summary is the error message.
After init, next is npm install, npx shipvo run android and npx shipvo publish --json.
Migration: keys rotate sign --json used to print the bare signed envelope. It now prints the standard envelope with the signed envelope in data.envelope.
shipvo migrate --plan
Read-only. Run it in an app that uses expo-updates or react-native-code-push. It changes no files. With --json it prints the standard envelope with next steps. In an app with neither it exits 0 and says there is nothing to migrate.
For expo-updates, it lists the entries it finds (dependency, plugin entry, updates and runtimeVersion keys in app.json), the steps to switch, and the order that keeps installed apps safe. See Migrate from EAS Update.
For CodePush, it lists the dependency, codePush() wrapper and CodePush.sync calls, CodePushDeploymentKey and CodePushPublicKey entries, and appcenter codepush commands, each with file and line, then prints ordered steps (system: "codepush" in --json). See Migrate from CodePush.
shipvo migrate --apply
Makes the safe edits for the switch from EAS Update: removes the expo-updates dependency and plugin entry, and the updates and runtimeVersion keys from app.json. Each changed file is copied to .shipvo/migrate-backup/ first. It refuses a dirty git tree unless you pass --force. It does not run shipvo init; it prints it as a next step, with the rest of the plan. A second run exits 0 and says there is nothing left to do. --json prints the standard envelope with next steps. See Migrate from EAS Update.
For CodePush apps, --apply edits only these things, each file copied to .shipvo/migrate-backup/ first:
- Single-line
codePush({...})(App)becomesApp,CodePush.sync(...)becomesRuntime.checkForUpdate(true)andCodePush.notifyAppReady()becomesRuntime.markHealthy(). Thereact-native-code-pushimport becomesimport { Runtime } from "@shipvo/runtime".checkForUpdate(true)drops the original arguments (install mode, callbacks) and the returned status, so review each of those call sites. If a named import such asInstallModeis still used, the import stays and the call is listed as a manual step. CodePushDeploymentKeyandCodePushPublicKeyare removed fromInfo.plistandstrings.xml.- In
package.json,react-native-code-pushis replaced by@shipvo/runtimeand@shipvo/device, with@shipvo/clias a dev dependency. It does not run your package manager.
Native bootstrap code is never edited: MainApplication.java/.kt, AppDelegate.m/.mm/.swift, *.gradle and Podfile often still call CodePush, and the native build breaks until you change them by hand. Any of those files that mention CodePush or code-push are listed as manual steps. appcenter codepush scripts and CI lines are never edited. Neither are CodePush calls it cannot rewrite (for example a call that spans several lines). It prints each with file and line as a manual step, and lists them under data.manual in --json. A dirty git tree is refused with code dirty_tree unless you pass --force. A second run changes nothing and exits 0.
shipvo lumi
shipvo lumi [android|ios] [--ui-port 4547] [--no-open] builds the app, opens it in your browser on Shipvo Phone and shows the Lumi sidebar: a live feed of each action, findings as they appear, coverage (screens and controls tried) and a command box. It runs on your machine and answers only requests from its own page.
Commands (plain text, no AI): test my app, test <flow>, try <flow> with bad input, stop, replay bug <n>, help. A flow is a name from routes in shipvo.json or a control on the start screen, such as cart. Unknown text gets the list of commands.
--json for store, app and sim
Every store subcommand (setup, status, details, screenshots, testers), every app subcommand (create, list, delete) and sim take --json and print the same { ok, code, summary, data, next } envelope. Stdout holds one JSON line; text and build output go to stderr. Without --json nothing changes. sim prints its envelope once the simulator is listening and keeps running. store testers --json now returns the guide inside data.
Exit codes: 0 ok, 1 failed, 2 usage error.
| Command | code on success | data |
|---|---|---|
store setup | plan_written | { file, answers } |
store status | in_progress, live | { done, total, marks, steps: [{ id, title, state }] } |
store details --dry-run | details_written | { app, rows, unknown, filled, total } |
store screenshots | screenshots_ready | { out } |
store testers | testers_guide, testers_updated | the guide, plus api when --play-key is used |
app create | created | { app_id, created, expires_at, token_file } |
app list | listed | { count, apps } |
app delete <id> --yes | deleted | { app_id } |
sim | listening | { url, port, app_id, watch } |
Failure codes and their exit codes:
code | Exit | Meaning |
|---|---|---|
usage | 2 | Bad flag, value or subcommand |
no_plan | 2 | store status found no store-plan.json |
unknown_step | 2 | store status --mark named a step that does not exist |
no_browser, no_sim | 2 | sim could not find Chromium or @shipvo/sim |
no_config | 1 | store ran in a folder with no shipvo.json |
not_signed_in | 1 | app needs shipvo login first |
not_found | 1 | app delete found no such app on your account |
register_failed | 1 | app create was refused by the control plane |
remote_failed | 1 | store testers could not update the Play track |
screenshots_failed | 1 | A store screenshot failed its size or format check |
port_in_use, build_failed, sim_exited | 1 | sim could not start |
failed | 1 | Any other error; summary holds the message |
On failure data is {}. No envelope holds a token or key.