@nimbus-sh/cli

CLI for Nimbus: scaffolding, token mint/verify, session helpers, and runtime cache operations.

Install

npx @nimbus-sh/cli --help
npx @nimbus-sh/cli init my-app
npx create-nimbus-app my-app

From this repository:

bun packages/cli/src/bin.ts --help
bun packages/cli/src/bin.ts init my-app
bun packages/cli/src/scaffold-bin.ts my-app

Verbs

nimbus init [directory]

Scaffolds a Nimbus-powered Workers project. . uses the current directory. The generated app embeds the interactive Nimbus UI and enables the authenticated remote sandbox API. Add application-specific auth routes in src/index.ts when you are ready to mint user tokens from your backend.

nimbus init my-nimbus
cd my-nimbus
npm install
CLOUDFLARE_ACCOUNT_ID=<account-id> npx @nimbus-sh/cli setup cloudflare --name my-nimbus
npx wrangler secret put JWT_SECRET
npx wrangler deploy

create-nimbus-app <name>

Scaffolds a new Nimbus-powered Workers project with the same template as nimbus init.

create-nimbus-app my-nimbus
cd my-nimbus
npm install
CLOUDFLARE_ACCOUNT_ID=<account-id> npx @nimbus-sh/cli setup cloudflare --name my-nimbus
npx wrangler secret put JWT_SECRET
npx wrangler deploy

Flags:

| Flag | Default | What | |---|---|---| | --name <wrangler-name> | project name | Becomes the deployed Worker name. | | --template <name> | worker-only | Only worker-only ships in v0.1. | | --force | off | Overwrite existing directory. |

nimbus setup cloudflare

Creates the R2 buckets referenced by the scaffolded wrangler.jsonc and uploads the Python, Ruby, and clang runtime catalog.

CLOUDFLARE_ACCOUNT_ID=<account-id> npx @nimbus-sh/cli setup cloudflare --name my-nimbus

If Wrangler reports Cloudflare R2 error 10042, enable R2 in the Cloudflare Dashboard once for the account, then rerun the setup command.

Flags:

| Flag | Default | What | |---|---|---| | --name <worker-name> | required | Worker name and default bucket prefix. | | --bucket-prefix <prefix> | --name | Prefix for npm cache buckets. | | --runtime-bucket <bucket> | nimbus-runtime-cache-public | Runtime catalog/blob bucket. | | --skip-runtimes | off | Create buckets only. |

nimbus token mint

JWT_SECRET=<hex> nimbus token mint --tenant acme --sub alice [--ttl 3600]
# Prints the JWT to stdout. Pipe with `> /tmp/jwt` or `| pbcopy`.

Flags:

| Flag | What | |---|---| | --tenant <id> (required) | Sets tn claim. | | --sub <id> | Sets sub claim. | | --ttl <sec> | Token lifetime in seconds. Default 3600 (1h), max 2,592,000 (30d). | | --scopes <a,b> | Comma-separated capability scopes. | | --sid <id> | Pin token to a specific session ID. |

Use --scopes sandbox:use --sid <sandbox-id> for remote SDK calls through Nimbus.connect(...).

nimbus token verify <token>

JWT_SECRET=<hex> nimbus token verify eyJhbGciOi...
# Prints the verified claims as JSON.

Exit codes: 0 success, 65 token-validation failure, 78 env missing.

nimbus runtime sync

Uploads runtime blobs/manifests and updates the runtime catalog through the public CLI wrapper. This is the user-facing path for Python, Ruby, and clang runtime cache operations.

CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public clang
CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public python
CLOUDFLARE_ACCOUNT_ID=<id> nimbus runtime sync --bucket nimbus-runtime-cache-public ruby

Runtime versions default to the shipped catalog versions (clang@binji-2020, [email protected], [email protected]) unless explicitly overridden as name@version.

nimbus runtime list

nimbus runtime list
# JSON catalog: [{name, version, size_mb, license}, ...]

nimbus session new

NIMBUS_ENDPOINT=https://my-nimbus.workers.dev nimbus session new
# {"sessionId":"pretty-otter-1234","url":"https://.../s/pretty-otter-1234/"}

Programmatic use

Every verb is also exported as a function:

import { mintToken, syncRuntimes, scaffold } from '@nimbus-sh/cli';

mintToken(argv) and friends return a Promise (process exit code). Stdout / stderr write directly via process.stdout/process.stderr.

Engines

Requires Node >= 20 (for native fetch, crypto.subtle, etc.).

MIT.