Vibes DIY
Vibes DIY / Docs
creator docs · cli

The CLI handbook

Everything you can do in the Vibes DIY web UI — and a good deal you can't — is scriptable from the shell. There's nothing to install: every command runs as npx vibes-diy <command>. This page is the tour by task; the command reference is the complete flag-level contract, generated from the CLI's own help output. For the story of building whole sites with one command, see the generate case study.

Sign in once (or never, in CI)

shnpx vibes-diy login

opens a browser flow and enrolls this machine with a device certificate — that cert is the credential for everything below; there are no API keys. For headless environments (CI, containers), export the enrollment's keybag file via the VIBES_DEVICE_ID env var instead — the exact recipe, including why it's the keybag JSON and not a bare id, is in the CI lane pattern.

Act as a specific handle (--handle)

One account can hold several handles (your public you/… names). One is your default — the identity every command uses when you don't say otherwise. To act as a different one of your handles for a single command, pass --handle <slug>:

shnpx vibes-diy db put --vibe you/potluck --db signups --handle you-bot '{"rsvp":"yes"}'
npx vibes-diy push --handle you-bot          # publish under you-bot this once

--handle is stateless: it overrides the acting handle for that one invocation only and never changes your saved default. (To change the default itself — a persistent switch — use npx vibes-diy user-settings --set-default-handle <slug>.) The handle you pass must already be bound to your account; you can't act as someone else's handle.

Every command that acts as an identity accepts it — push, edit, pull, generate, put-asset, versions, publish, unpublish, and all db, secrets, and developer subcommands. It's the clean primitive for CI or a shared device that should write as a dedicated bot handle without disturbing whoever's default is set on that machine.

Ship apps from the shell

shnpx vibes-diy system > RULES.md     # the coding rules the generator follows
# write App.jsx (and optionally access.js, backend.js) …
npx vibes-diy push                   # deploy — prints a live HTTPS URL

Or skip the writing part entirely:

shnpx vibes-diy generate "a potluck signup with dish categories"
npx vibes-diy edit you/potluck "add a vegetarian filter"

generate runs the same codegen pipeline as the web UI and deploys the result; edit sends a follow-up prompt to an existing vibe, writes the changed files to disk, and pushes live. Round-trip an app you already have with pull / push:

shnpx vibes-diy pull you/potluck --dir ./potluck   # draft by default; --published for the live release
npx vibes-diy push                                # from that directory

Versions, publish, unpublish

shnpx vibes-diy versions you/potluck   # every release: fsId, mode, seq — ● marks published
npx vibes-diy pull you/potluck --fsId <id>   # retrieve any historical version
npx vibes-diy publish you/potluck    # promote the latest draft to production
npx vibes-diy unpublish you/potluck  # reversible takedown — code, data, grants all kept

Publishing only ever mints a new production release; it never destroys history, and unpublish is a tombstone you can lift with publish. One caveat that matters when testing: access.js and backend.js always run the live release — old fsIds serve pinned pages, not pinned backends — so stage risky backend changes under a secondary slug.

Your app's data is scriptable

shnpx vibes-diy list                                    # your vibes
npx vibes-diy db list  --vibe you/potluck             # its databases
npx vibes-diy db query --vibe you/potluck --db dishes # latest docs
npx vibes-diy db get   --vibe you/potluck --db dishes <docId>
npx vibes-diy db put   --vibe you/potluck --db dishes '{"kind":"dish","name":"chili"}'
npx vibes-diy db del   --vibe you/potluck --db dishes <docId>
npx vibes-diy db subscribe --vibe you/potluck --db dishes   # live change tail

subscribe streams document changes as they commit — a real-time tail you can pipe into anything. Identity semantics worth knowing: the read commands (get/query/list) use the owner's admin-mode override implicitly, which is why the CLI can read a document your browser session can't; the write commands are honest by default and only override with an explicit --admin. The full story is in the access model. These commands are also how external workers join an app's workflow — see doc-status state machines.

Secrets, assets, transcripts

shnpx vibes-diy secrets set STRIPE_KEY --vibe you/potluck   # backend-only, write-only
npx vibes-diy secrets ls  --vibe you/potluck              # names + last4, never values
npx vibes-diy secrets rm  STRIPE_KEY --vibe you/potluck

npx vibes-diy put-asset ./hero.jpg    # content-addressed upload — prints CID + public URL

npx vibes-diy codegen-log you/potluck # the builder↔LLM transcript that generated the app
npx vibes-diy app-chats  you/potluck  # the app's own runtime AI conversations

Secrets surface as ctx.secrets in backend.js. put-asset returns an immutable, publicly served URL — handy for images your vibes or blog posts reference. The two transcript commands answer different questions: codegen-log is how this app got built, app-chats is what the app's users asked its AI.

The CLI teaches you the platform

shnpx vibes-diy skills            # list the codegen skill docs
npx vibes-diy skills backend    # dump one — the same doc rendered at /docs/reference/
npx vibes-diy themes            # the design themes
npx vibes-diy system            # the base system prompt itself

These dump the exact documents the code generator reads — the same corpus published as the generator's reference, available offline in your terminal.

Mount your vibes into any AI agent

shnpx vibes-diy mcp

starts an MCP server (stdio transport) exposing list/get/put/query/delete over your vibes' data — so Claude Code, Cursor, or any MCP-capable agent can read and write your apps' databases with your device credential and your access rules. npx vibes-diy mcp --help prints the client setup snippet.

Where to go next

← Docs hub