@karpo.dev/cli

The karpo command line: it scaffolds an app, compiles the schema tree, publishes it through the platform gateway, generates the typed client, and runs the whole local platform.

npm install --save-dev @karpo.dev/cli

Requires Node.js ≥ 20.

Commands

| Command | What it does | | --- | --- | | karpo init | Scaffold a new Vite + TypeScript + React app with Karpo wired up. | | karpo setup | Add Karpo to an existing Vite + TypeScript app. | | karpo login | Sign in to a gateway with your WorkOS account; the credential lands in ~/.karpo/credentials.json. | | karpo link | Provision this project's organization, tenant, and environment on a gateway, and record them in karpo.json. | | karpo generate | Emit types.ts, db.ts, and schema.json from the local schema files. | | karpo push | Compile the schema tree and publish it through the platform gateway. | | karpo seed | Apply karpo/seed.ts to a gateway — the fixture workspaces, and their memberships to a signed-in user. | | karpo dev | Run the whole local platform: engines, gateway, schema, seed, and your app. |

karpo --help prints the same list; karpo --version prints the version.

Getting started

npx @karpo.dev/cli init my-app
cd my-app
npm install
npx karpo login                   # sign in with your own account, once per gateway
npx karpo link                    # provision the organization, tenant, and environment
npx karpo push                    # publish this schema to it
npm run dev

init writes the scaffold and generates the typed client immediately, so the project typechecks before anything is published. The scaffolded app is anonymous-first: a visitor gets a real, syncing identity on first paint, so there is no sign-in screen to build before the app does something.

Credentials

Everything that writes to a gateway — link, push, seed — authenticates as you. karpo login opens your browser, signs you in with your own WorkOS account (Authorization Code + PKCE, over a redirect back to 127.0.0.1), and stores a credential that renews itself. Nothing is handed out and nothing is shared; there is no operator token to go and ask for.

For a given gateway, the credential is looked up in this order:

1. KARPO_OPERATOR_ACCESS_TOKEN in the environment — a WorkOS access token, which is how CI holds one without a browser to open.
2. ~/.karpo/credentials.json (written by karpo login, 0600, keyed by origin — logging in to one gateway never signs you out of another). An access token that has aged out is refreshed silently before the command proceeds; a refresh the provider refuses ends the command naming karpo login, having done nothing.
3. For localhost only, the credential karpo dev minted for this project in .karpo/dev/secrets.json. It authenticates that stack and is never sent anywhere else.

There is deliberately no --token flag on any command, login included: argv is world readable through ps, and a value karpo can neither verify nor renew is a way to be signed in as nobody.

Step 1 is the only one not tied to a single gateway: an exported variable is sent wherever the command is pointed, which is karpo.json's platformUrl. A command about to present it to a gateway karpo login has never stored a credential for says so first, naming the origin.

Configuration

karpo.json at the project root holds schemaDir, generatedDir, platformUrl, the organization and tenantId that own the project, environment, the publishableKey that karpo link writes back, and the dev block. The publishable key is not a secret — it ships inside app bundles — and it is what tells the gateway which environment a push lands in. --target local points a checkout at a locally running stack instead of the deployed environment; --url points anywhere.

karpo dev is for this repository's checkout: it builds and spawns the Rust engines and the API gateway alongside your app. A standalone project uses a deployed environment and runs its own dev server.

Programmatic use

The package also exports its pipelines — runCli, runPushPipeline, runGeneratePipeline, startDev, loadConfig, resolveOperatorCredential — for scripts and tests that need the CLI's behavior without a subprocess.

Documentation

• CLI reference: https://karpo.dev/cli
• Quickstart: https://karpo.dev/quickstart
• Source: https://github.com/Chirich-GmbH/karpo-core (packages/cli)