@isomorph.ai/cli

The Isomorph development kit CLI: sets up, runs, checks and ships an Isomorph app. It is meant to be driven by an AI coding agent (Claude Code or Codex) on your behalf; you can also use it directly.

Quick start (no coding needed)

You describe the app in plain English inside Claude Code or Codex; the agent installs and runs everything. One paste, once per computer:

npx -y @isomorph.ai/cli agent-setup

Paste that line into Claude Code or Codex (or a terminal). It teaches both agents the kit by installing the isomorph skill for each (~/.claude/skills/isomorph/SKILL.md, ~/.codex/skills/isomorph/SKILL.md, with the kit's rules beside it as core.md, integrations.md, ai.md and jobs.md) and never touches your other skills or instructions. A skill is read only when the task matches it — a folder with .isomorph/, an app you ask for on Isomorph — so the agent works exactly as before on everything else. (Releases before 0.1.34 put the guide in your global Codex instructions, ~/.codex/AGENTS.md, where every Codex session read it; running the line again takes that block out and leaves the rest of the file as it was.)

That npx line runs the current release; isomorph init, dev, check and deploy afterwards run whatever isomorph is installed on this machine. A CLI older than what your company's Isomorph platform accepts is refused by every company command in under a second (CLI_UPGRADE_REQUIRED), with the fix: npm i -g @isomorph.ai/cli.

Then, in an empty folder:

1. Say what you want, for example "Build me a small app where my team can vote on lunch options and see the results live."
2. Say "run it" — the agent starts it and gives you a link to open.
3. Say "check it" — the agent runs the checks and tells you in plain words what passed and what it fixed.
4. Say "I need Slack" (or Gmail, or the warehouse) — the agent asks IT for access and tells you when it is approved.
5. Say "ship it" — the agent puts a private preview online and gives you the link; "make it live for everyone" promotes it after you have tried it.

The only step you do yourself is the company sign-in: when the agent runs isomorph login, your browser opens and you sign in there. You need Node 22+ on macOS Apple silicon, Linux x64 or Windows x64; Isomorph installs its local database, files and gateway without Docker. Full walkthrough: docs/vibecoding.md.

Commands

isomorph agent-setup                                        install the `isomorph` skill for Claude Code and Codex; idempotent
isomorph init --app-root <path> [--adopt] [--upgrade] [--json]   starter app in an empty folder or around data files (also runs agent-setup); a folder with an app and no kit is refused with the choices that can succeed (APP_EXISTS); --adopt adds the kit files to a Vite + React app in place; --upgrade re-pins the kit bundle and runs the checks
isomorph package --app-root <path> [--out <file>] [--json]  zip an app built without the kit for the console's Upload package (local; .env files included, node_modules/build output/.git left out)
isomorph dev --app-root <path> [--reset] [--detach] [--group <name>]... [--json]  run the app locally on one loopback origin; --detach starts it in the background and prints {origin, pid} once it answers; --group puts the local person in a company group
isomorph stop --app-root <path>                             stop local services, keep data
isomorph check --app-root <path> [--integrations] [--json]  types, build, migrations, database gate, write probe, journeys, coverage; --json prints the whole report
isomorph integrations catalog --app-root <path> [--json]   the company's connections as .isomorph/integrations.json names them, with approved channels/views per environment
isomorph integrations request <connection> --app-root <path> [--reason <text>]   one request per connection; IT approves it once for every environment (`isomorph dev` and `isomorph deploy` file it for you)
isomorph integrations status --app-root <path> [--json]
isomorph connect <work-email | company-start-url>                 once per company; then isomorph login | logout
isomorph secure --app-root <path> [--json]                  scans the code in the company's AWS account (committed credentials, vulnerable dependencies, insecure patterns) and prints the verdict; exit 1 when it blocks, with every blocking finding and each "No fix available" dependency
isomorph deploy --app-root <path> [--accept-security-risk] [--json]   checks (when not already passed for this code), then one call that runs the pre-flight and opens the deployment; the package is handed over and Isomorph saves, verifies and deploys it; prints the protected link
isomorph status | retry | promote [--app-root <path>] [--operation <reference>]   (--app-root defaults to the current folder; --operation to the deployment last started from it; promote: [--confirm-tested])
isomorph settings dismiss <NAME> [--app-root <path>] [--json]   mark a key the deployment asked for as not needed (the console's "Not needed"); recorded under your sign-in, and the paused deployment resumes when it was the last missing key

deploy reads the app's name, description and audience from .isomorph/app.json (written by init; edit it before shipping) and prints the three values before it starts. It then asks Isomorph once whether the app can deploy — the access request for every declared connection, the company's AI setup when the app calls governed AI, and this CLI's version — and refuses with exit 2 naming every blocker and its fix (DEPLOY_BLOCKED, or INTEGRATIONS_NOT_READY / AI_NOT_READY / CLI_UPGRADE_REQUIRED when the blockers are all of one kind). The same package (by digest) always continues the same deployment, so running deploy again after an interruption resumes rather than restarts; a different package while one is still deploying is refused (DEPLOY_IN_FLIGHT) naming the operation to follow. A deployment of yours that is only paused waiting for keys, data access or analysis does not block you: deploying changed code replaces it.

Who may open the app: audience lists colleagues' work emails, and the optional audienceGroups lists company groups exactly as the company's identity provider sends them at sign-in ("audienceGroups": ["Finance"]). Group names are never checked against the identity provider: one nobody carries lets nobody in and is not an error. Leave audienceGroups out to keep the groups set in the console; a list, even [], replaces them. isomorph share applies an audience-only change without a release.

deploy, status --wait, retry and promote follow the deployment for up to --max-wait <seconds> (default 30 minutes). Past that they exit 0 with status: "RUNNING" and the isomorph status --app-root . --operation <reference> --wait --max-wait 120 --json that continues the same deployment — a bounded wait is not a failure, and never a reason to start another deploy.

promote never prompts: --confirm-tested is the one flag that means the person has opened the preview and it works. (productionise, the command's name until 0.3.4, was accepted as an alias for one release and is no longer a command.)

There are two ways onto Isomorph and init is where the folder decides. An empty folder (or one holding only .git, a README, a licence, node_modules or editor and agent files) gets the starter. So does a folder that holds only data — no package.json, no src/, no index or source file (.ts, .tsx, .js, .jsx, .mjs, .html): the starter is created around the files, none is overwritten, and one line names them (Kept 2 existing files (data.csv, rows.csv); read them from the app.). A folder that already is a kit app (it has .isomorph/kit.lock.json) is kept as it is and told its next commands (dev, check, deploy). A folder with an app and no kit is never adopted silently: init refuses with exit 2, APP_EXISTS, and the choices that can succeed, in order — isomorph init --app-root <dir> --adopt (add the kit in place; offered only when package.json depends on vite and react, otherwise APP_UNSUPPORTED), isomorph init --app-root <new-empty-folder> (start a new kit app), then isomorph package --app-root <dir> (package the app as it is for the console import). With --json the choices are in error.details.choices as { id, command, description }, so an agent relays them and runs the one the person picks. package is local (no company, no sign-in): it scans the tree the way deploy does, includes the app's .env files (the console reads their values into encrypted defaults and never commits the files), refuses private keys and other secret-bearing paths, and writes a deterministic isomorph-import.zip (or --out <file>) whose result names the path, file count, bytes, sha256 and the one next step: upload it in the console (Add app → Upload package), or connect the repository there instead. A kit app is refused (KIT_APP): it deploys with isomorph deploy.

isomorph --help prints the full usage. Local commands need no company sign-in; integrations and shipping do.

Development

Built from the governance control plane repository: npm ci, npm run build --prefix packages/harbour-cli, tests in tests/cli-kit.test.ts and tests/cli-packaging-contract.test.ts. Merge is release (docs/adr/0021): a PR that bumps the version in packages/harbour-cli/package.json — the one file that carries it; src/version.ts reads it at runtime — is tagged cli-v<version> by CLI release automation the moment it lands on main, and Release Isomorph CLI publishes it through npm trusted publishing once a stage runs it (docs/adr/0074): as X.Y.Z-beta.0 under beta when beta's server carries X.Y.Z, and as X.Y.Z under latest when production's does — so production builders get a CLI only with the production server it was built for. Beta's console and start profile name @isomorph.ai/cli@beta. A version that already exists on npm is never republished, and a tag never moves backwards. When the release embeds a new kit bundle, bump harbour.kitBundle.version in the same PR and run npm run kit-bundle:sync there: it regenerates the embedded manifest and the server's src/kit-bundle-expectation.generated.ts from one fetch. 0.2.0 and 0.2.1 (the rename) were published by hand from their merge commits before the trusted publisher existed for @isomorph.ai/cli, which is why their cli-v release runs show red.

Connect with isomorph connect [email protected]: the CLI asks the platform which company admits the email's domain (https://platform.isomorph.ai/start/getlokal.com.json — the same policies that admit the person at sign-in) and saves that company's profile. Production (platform.isomorph.ai) and beta (beta.platform.isomorph.ai) have separate companies, so when production answers that no company admits the domain the CLI asks beta the same question; any other production answer, an outage included, is final. ISOMORPH_PLATFORM_URL names the one platform to ask instead. The console that answered is saved with the profile, and deploy links there. Only the domain is sent, not the email. When no company admits the domain, or more than one does, the CLI prints the platform's sentence (ask IT, or run the printed isomorph connect <link>) and saves nothing; a company's console page (<console>/t/<company>) is accepted as the link. connect then signs in (the browser opens) unless this device already is, ISOMORPH_TOKEN is set, or --no-login is passed; isomorph login signs in again later. Signing in prints the company and what IT has set up there. Signed in, isomorph dev sends AI calls from actions/ and jobs/ to the company's development AI connection; signed out they get a canned reply, and dev --real additionally lets them call company systems. Company sign-in and access checks still apply.

Owner-authorised background integrations

Read isomorph integrations status --app-root . --json for consents: the caller's connected accounts and per-environment background flags. Include background use of the account by the app in the setup approval, naming the account and environment; reuse explicit approval already given. Then run isomorph integrations request <connection> --app-root . --allow-background preview --json and verify status. Omit the flag for ordinary requests. This records consent on the existing link; it neither approves IT access nor sends a message. The existing console control can revoke it.

If the account needs connecting, use integrations connect <connection> --app-root . --return-url <dev-origin>/_harbour/integrations/oauth/complete --json and follow nextStep. Run isomorph agent-setup after updating the CLI to refresh the AI instructions; init also installs them. No new endpoint, login, runtime or SDK change is needed.