Marketplace

Shipped

Not every extension is authored from scratch. The marketplace lets you install a published hook or conduit into your instance with one command, and — if your instance is an approved publisher — publish your own for others to install.

Installing and publishing are CLI-only today: there is no in-product marketplace to browse. You install an extension by name with turbobase ext install.

Before you start

Both commands run against the instance you’re signed in to — the install lands in that instance’s store. Publishing is gated separately: only approved publishers can push an extension to the registry.

The registry credential

The marketplace is the one part of the CLI that does not run on your stored PAT. It talks to the Turbobase registry rather than to your instance, so it takes its own credential — two environment variables, and you need both:

export TURBOBASE_REGISTRY_URL=…    # the registry endpoint, given to you with the token
export TURBOBASE_REGISTRY_TOKEN=…  # ask Turbobase support to issue one

Ask Turbobase support to issue a registry token for your instance. They give you both values together. The token is shown exactly once when it is created — store it in your secret manager, not in a repo. If you lose it, ask for a new one; issuing a replacement retires the old one.

Three things worth knowing about it:

• It is not one of your instance’s internal credentials. It authorises the marketplace routes and nothing else — it cannot read or write your instance’s data, and it is not the credential your instance uses internally.
• It can be revoked on its own. If it leaks, ask support to revoke it. Your instance keeps running normally; nothing else is affected.
• Both variables must come from the same place. The CLI will not pair a URL you set with a credential it found somewhere else in your environment, and TURBOBASE_REGISTRY_URL must be https:// — the token travels to it as an Authorization header, so it is never sent over a plaintext connection.

With either variable missing, both commands stop before making a request:

turbobase: marketplace not configured — set TURBOBASE_REGISTRY_URL and TURBOBASE_REGISTRY_TOKEN.

ext install — install a published extension

turbobase ext install acme-recipes              # latest version
turbobase ext install acme-recipes@1.2.0        # pinned version
# installed acme-recipes@1.2.0 → ext_xyz (status=active, created).

The CLI fetches the published bundle from the marketplace, parses its metadata, and deploys it — an install lands active, with no proposal to approve. On the Extensions tab it then reads as CLI deploy, the same origin a hook you deployed yourself carries. A non-admin personal access token (PAT) gets an install forbidden (403).

Binding a connection at install

A published bundle is connection-agnostic: it never bakes in a specific connection. If the manifest declares a { type:'connection' } input, you bind one of your instance’s connections at install time:

turbobase ext install acme-recipes --connection conn_123
# installed acme-recipes@1.2.0 → ext_xyz (status=active, created) bound to connection conn_123.

Omit --connection for such an extension and the CLI tells you which source the extension wants and refuses until you bind one. The runtime then acts only on that connection.

ext publish — publish to the marketplace

turbobase ext publish hooks/recipe.ts \
  --name acme-recipes \
  --pkg-version 1.0.0 \
  --manifest manifest.json
# published acme-recipes@1.0.0 (kind=hook) to the marketplace.

The CLI derives the kind (hook vs conduit, exactly as deploy does), validates the optional manifest locally, and publishes. Flags:

Flag	Meaning
--name <name>	Required. Marketplace package name (lowercase, e.g. acme-recipes).
--pkg-version <version>	Required. Semver-ish (e.g. 1.0.0). Not --version — that is the CLI’s own version flag.
--manifest <file>	Optional JSON manifest declaring inputs[] (including { type:'connection' }) and capabilities.

The publisher allowlist

Publishing is gated by an admin-managed publisher allowlist. An instance whose slug isn’t on the list gets:

turbobase: publish forbidden (403) — this instance is not an approved publisher.
Ask staff to add this slug to the publisher allowlist.

Re-publishing an existing name@version returns 409 (bump the version).

The connection-agnostic contract

A published bundle must not bake in a literal connection_id — that’s validated locally before the bundle hits the wire. Instead, a manifest declares a { type:'connection' } input, and the installing instance binds its own connection at install time (above). This keeps a published extension portable across every instance that installs it.

Install vs. author

	Install	Author
Source	A published marketplace bundle	Your own hooks/ / conduits/
Command	turbobase ext install	turbobase ext deploy
Lands as	Active, straight away	Active, straight away
Origin on the Extensions tab	CLI deploy — an install is not badged apart from a deploy	CLI deploy, or Code baseline for one your instance ships with
Connection	Bound at install via --connection	Set in your own config

Next steps

• Writing hooks / Writing conduits — author what you publish.
• Deploy, plan, promote — ship a self-authored extension instead.
• CLI reference — ext install / ext publish flags.