CLI overview

Shipped

The turbobase CLI is the command-line interface to a live instance. One binary builds and ships the hosted apps your team uses, authors and deploys extensions — hooks, conduits and processes — promotes a reviewed configuration between environments, and generates the files an AI coding agent reads before it starts working.

Every subcommand wraps the same library functions the authoring MCP server exposes, so the command line and the Claude Code surface never drift.

The CLI talks to a running Turbobase instance over its HTTP API with a personal access token. It is not a way to stand up Turbobase yourself — your instance is provisioned and operated as a managed service.

Install

One command, on macOS and Linux:

curl -fsSL https://console.turbobase.io/install-cli.sh | bash

…or on Windows:

powershell -c "irm https://console.turbobase.io/install-cli.ps1 | iex"

The installer downloads the current build, verifies its checksum, and puts turbobase on your PATH. Everything lands in ~/.turbobase — no sudo, no package manager, nothing written outside your home directory. Re-run the same command any time to upgrade; it swaps the version in place.

Node.js 22, or 24 and newer, is the only requirement, and if your machine doesn’t have one the installer fetches a private copy into ~/.turbobase/runtime rather than touching your system Node.

turbobase --version

You can also find both commands in your instance under Settings → Integrations & AI access, alongside a turbobase auth login line with your instance URL already filled in.

Other ways to install

npm, if you’d rather manage it with your other global tools:

npm install -g @turbobase/cli

Optional extras

turbobase ext test and turbobase ext replay compile your extension and execute it in a real sandbox, which needs two native packages. They aren’t part of the base download — install them once, when you first need them:

turbobase ext extras install
turbobase ext extras status

Every other command works without them.

Every command is discoverable from the binary itself. The top level is fifteen entries — thirteen nouns you drill into, plus two commands that stand on their own — so start there and open the one you want:

turbobase --help            # all fifteen
turbobase ext --help        # author, verify, ship, observe extensions
turbobase ext new --help    # hook | conduit | process

Each row links to that part of the CLI reference, where every verb has its flags and an example.

Group	What lives there
auth	Sign in, sign out, and pick the active instance.
project	Scaffold the project; generate the files an agent session reads.
ext	Author, verify, ship, and observe extensions — plus the marketplace.
apps	Hosted apps served at /a/<slug> — scaffold, push, deploy, preview, promote.
kb	Write findings into the instance’s knowledge base.
skills	Write the standing rules your instance’s agents follow — push, publish, roll back.
tables	Custom tables of your own, for the data no connected system holds.
guardrails	Decide which write-backs may leave your instance, and dry-run one before you do.
relationships	Which linked record pairs re-read each other when one side is saved, and switching either re-read on.
data	Act on one record — today, link a row to the record your source already created.
processes	What runs in the background: what is deployed, what it did, and starting or undoing a run.
release	Ship your project from your own CI — deploy, status, rollback, list.
sandbox	Ephemeral local instances to replay against.
logs	Every log under one noun — guardrails, hooks, scheduled tasks, conduits and sync.
mcp	A local stdio authoring server, for clients you point at a process rather than a URL.

Authenticate — turbobase auth login

The CLI authenticates as an instance admin and stores a personal access token (PAT, tb_pat_…). You point it at your instance’s base URL; one operator laptop can hold credentials for many instances at once.

Mint a PAT in your Turbobase app on the Access tokens page — your account menu, or /settings/tokens — then hand it to the CLI. A token belongs to a Turbobase account, so that page is not offered to administrators who opened the app from inside NetSuite. This is the only sign-in path — there is no browser flow, so the same command works identically on a laptop, a headless box, and a CI runner:

turbobase auth login --base-url https://acme.turbobase.app --token tb_pat_xxxxxxxx
# signed in to https://acme.turbobase.app — now the active instance.

Useful flags:

Flag	Meaning
--base-url <url>	Required. Your instance, e.g. https://acme.turbobase.app.
--token <tb_pat_…>	Required. The PAT to store.
--no-verify	Skip the post-sign-in connectivity/token probe.

After storing the token, login probes the instance: it checks that the base URL actually serves the /v1 API and that the token authenticates, and prints a loud warning on a wrong host or a rejected token (stale, revoked, or for a different instance). The credential is stored either way; --no-verify skips the probe.

In CI, read the token from a secret rather than a literal — --token "$TURBOBASE_PAT".

Where credentials live — ~/.turbobase/credentials

login writes the PAT to ~/.turbobase/credentials, a JSON file with an active-instance pointer plus a tenants map keyed by base URL:

{
  "active": "https://acme.turbobase.app",
  "tenants": {
    "https://acme.turbobase.app": { "token": "tb_pat_…", "updatedAt": "…" },
    "https://beta.turbobase.app": { "token": "tb_pat_…", "updatedAt": "…" }
  }
}

The PAT is the only secret in the file; it is written 0600 (owner-only) so a shared host doesn’t leak it. Every other command resolves the token from here:

• With one stored instance, commands use it automatically.
• With several, the last one you signed in to (or a turbobase auth use target) is the active default; pass --base-url <url> to reach a different one. If there’s no active default, an interactive terminal lets you arrow-pick one (and turbobase auth use with no argument always does); in CI the command dies with a clear “multiple instances stored” message instead.

Override the directory for tests with TURBOBASE_HOME.

Scaffold an extension project — turbobase project init

turbobase project init scaffolds a Claude-Code extension project in the current directory — a CLAUDE.md authoring guide, a .mcp.json that points Claude Code at your instance’s MCP servers, a .claude/ directory (skills for generate-types / record-learning / mock-test / deploy, plus a SessionStart hook that refreshes types.ts and the settings.json that wires it), INSTANCE-LEARNINGS.md and TURBOBASE-FEEDBACK.md, and empty hooks/ and samples/ directories. It never overwrites a file that already exists (each is reported wrote or skipped) — with one exception: an existing .gitignore is merged, not skipped, so the rule ignoring .mcp.json always lands.

It runs signed out, too: with no stored credential it writes placeholders in .mcp.json and says so.

turbobase project init
#   wrote   CLAUDE.md
#   wrote   .mcp.json
#   wrote   .claude/settings.json
#   ...
#   wrote   hooks/.gitkeep
#   wrote   samples/.gitkeep
#
# init: N written, 0 skipped.

Author with Claude Code — .mcp.json and turbobase mcp

init drops a .mcp.json so Claude Code can drive the same authoring operations the CLI exposes. It wires two servers hosted on your instance, over HTTP:

Server	URL	Auth	What it gives the agent
turbobase-authoring	<base-url>/mcp/authoring	The PAT from your sign-in, written into the file	Scaffold a hook or conduit, generate types, dry-run against fixtures, deploy, tail logs, and the hosted-app verbs (list / create / pull / push).
turbobase	<base-url>/mcp	OAuth — your client opens a sign-in page on first use; no token is written	The data surface: catalog, record anatomy, knowledge base, and RLS-scoped reads.

Because the authoring tools and the CLI subcommands wrap the same library functions, what you can do conversationally in Claude Code is what you can do on the command line. Two deliberate exceptions: the MCP scaffold tools return the file’s path and contents rather than writing to disk, and there is no apps_deploy tool — deploying builds locally and uploads the result, which needs filesystem access the hosted server doesn’t have. Use turbobase apps deploy for that.

.mcp.json holds a live access token. The scaffold writes it 0600 and adds it to .gitignore. Keep it out of version control, and rotate the token if the file was ever pushed.

turbobase mcp is a separate local stdio server, for clients you would rather point at a process than a URL:

turbobase mcp --base-url https://acme.turbobase.app

Put a hosted app live — turbobase apps deploy

One command. It builds the directory, cuts a new version at /a/<slug>, and records that directory as the app’s newest source revision on your instance:

turbobase apps deploy reorder-desk ./reorder-desk

Recording the source is not bookkeeping. It is what lets you pull the app onto another machine, and it is what lets a change request someone files from inside the running app be applied to it — a built bundle cannot be turned back into a project, so an app whose source only ever existed on one laptop cannot be changed that way at all. App Management states it per app, and the in-app widget tells the person who filed the request.

The version is cut first and the source recorded after it, so a collection that fails costs you the revision and never the deploy. Read the line it prints: recorded N source files on the instance (rev R), or one beginning source not recorded: that names the fix. Credential files are never uploaded — .env, .env.* and .mcp.json, which holds a live token — and are listed on stderr so a withheld file does not look like a missing one.

Two flags are worth knowing:

• --no-source cuts the version and uploads nothing from the working tree. Reach for it on a CI loop that re-deploys on every commit.
• turbobase apps push is the other half: it records source and deploys nothing, for a tree you want stored before it is ready to go live.

Watch a conduit — turbobase logs and turbobase ext binding

A conduit produces two observable things at runtime: a run ledger (each attempt to carry a record across) and the bindings it created (the per-record link between the two sources). Two commands read them.

turbobase logs is the one platform event stream, and two of its filters are about conduits:

turbobase logs --conduit shop2ns:order --follow   # one bridge's run ledger
turbobase logs --subsystem conduits --since 2h    # every bridge, recent history

--conduit <id> reads that one conduit’s run ledger — a line per attempt, with its state, the hop count, the id the target answered with (to_ext=) and the reason a failed run gave. --subsystem conduits stays on the ordinary event stream and narrows it to conduit events across every bridge, which is the one to reach for when you do not yet know which bridge is misbehaving. Both take --follow to poll, --since <10m|2h|3d> to bound the window, and --json for one row per line.

turbobase ext binding lists and repairs the bindings themselves:

turbobase ext binding --status divergent   # every link out of step with its source
turbobase ext binding --retry bnd_123      # re-enqueue that fan-out write

--status filters on the binding’s write status (ok, pending, blocked, divergent, muted); divergent is the one that wants attention, meaning the canonical record is valid but the target source refused the write. --retry re-enqueues a single fan-out and needs an admin PAT. Only divergent and blocked bindings can be retried — anything else returns 409.

The same run ledger and counts are on the Conduits tab of /data/extensions in the app, with a 14-day runs-vs-failures chart over the top.

Terminal output

On an interactive terminal the CLI renders colour, a spinner for long-running calls, a live stage + percent bar for --follow jobs, aligned tables (auth status, apps list, ext binding), and boxed result cards for ext deploy / ext promote.

Progress is treated as chrome and written to stderr; command results — ids, tables, JSON, --reporter artifacts, streamed job logs — stay on stdout, so turbobase … | grep, > file, and CI pipelines are never disturbed. Colour is disabled automatically when stdout isn’t a TTY, and can be forced off with --no-color (before the command) or the standard NO_COLOR environment variable; --json and --reporter output is always plain regardless.

Next steps

• CLI reference — every command, its flags, and an example.
• Build apps on Turbobase — the hosted-app workflow the apps group drives.
• Writing hooks — the defineHook contract.
• Writing conduits — cross-source bridges.
• Sandboxes and testing — dry-run before you deploy.
• Deploy, plan, promote — config-as-code rollout.
• Marketplace — install and publish extensions.