CLI Skill

The vibe-coded.ai CLI skill is how vibes get built: the coding agent you already use (Claude Code, Cursor, Codex CLI, Gemini CLI) writes the code, runs it locally with vibe dev, and pushes it to the platform with vibe preview and vibe publish. This page covers installing the skill and every command it adds.

Prerequisites

• Claude Code (or another supported coding agent — see tool compatibility)
• A vibe-coded.ai account (sign up if you don't have one)
• jq installed (brew install jq on macOS, apt install jq on Debian/Ubuntu)
• curl and unzip available in your shell (pre-installed on macOS and most Linux distros)
• Node.js 18 or newer, with npm, for vibe dev (brew install node on macOS). The first vibe dev installs its local runtime with npm.

Install

One command:

curl -fsSL https://vibe-coded.ai/install.sh | sh

The installer and everything it puts on your machine are open source at github.com/vibe-coded-ai/vibe, MIT licensed, so you can read them before you run anything. This downloads the skill to ~/.claude/skills/vibe-coded-ai/, links the vibe binary into ~/.local/bin (or ~/bin when that one is on your PATH and ~/.local/bin isn't; set VIBE_BIN_DIR to choose), and links the skill at ~/.agents/skills/vibe-coded-ai (the cross-vendor Agent Skills path read by Codex CLI, Gemini CLI, Cursor, Amp and opencode). If a different program called vibe is already there, the installer leaves it alone and prints the full path to ours instead. Re-running it upgrades in place (the previous install is moved aside, not deleted). Once a day the CLI tells you when a newer version is out (“vibe X.Y.Z is available”) with the install line to run; it never updates itself. Set VIBE_NO_UPDATE_CHECK=1 to turn the notice off. Prefer to inspect first? Download the skill zip and read the install script before running.

Verify

vibe help

You should see the command list. The installer prints where it linked vibe. If neither folder is on your PATH, it uses ~/.local/bin and prints one command to paste once. For zsh it's:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Bash gets the same with ~/.bash_profile on macOS or ~/.bashrc elsewhere; fish gets fish_add_path. The installer never edits your profile itself.

Manual install

The installer is optional. To do the same by hand: extract the zip so you end up with ~/.claude/skills/vibe-coded-ai/, then link the binary:

mkdir -p ~/.local/bin
ln -s ~/.claude/skills/vibe-coded-ai/bin/vibe ~/.local/bin/vibe
chmod +x ~/.claude/skills/vibe-coded-ai/bin/vibe
mkdir -p ~/.agents/skills
ln -s ~/.claude/skills/vibe-coded-ai ~/.agents/skills/vibe-coded-ai

Tool compatibility (Codex CLI, Gemini CLI, Cursor)

The skill follows the Agent Skills standard, so it works in any compatible coding agent — not just Claude Code. The only difference is where each tool looks for skills. Pick the row for your tool:

Tool	Skills directory	Action
Claude Code	~/.claude/skills/	Default install above — found automatically.
Cursor	~/.claude/skills/ or ~/.agents/skills/	Reads both (its own ~/.cursor/skills/ too) — nothing extra.
Codex CLI	~/.agents/skills/	Symlink (below) — the installer creates it for you.
Gemini CLI	~/.gemini/skills/	Symlink (below), or rely on the ~/.agents/skills/ alias the installer already links.
Amp, opencode	~/.claude/skills/, ~/.agents/skills/	Both paths are read — nothing extra.
Claude Desktop	—	Doesn't read skill folders. Upload the skill zip under Customize › Skills in the app or on claude.ai.

Codex CLI, Gemini CLI, Cursor, Amp and opencode all read the cross-vendor ~/.agents/skills/ directory, and the installer links the skill there. If you installed by hand, or want Gemini's own folder, add the symlink yourself so you maintain a single copy:

# Codex CLI, Gemini CLI, Amp, opencode (the installer does this for you)
mkdir -p ~/.agents/skills
ln -s ~/.claude/skills/vibe-coded-ai ~/.agents/skills/vibe-coded-ai

# Gemini CLI's own folder (optional — the ~/.agents/skills alias also works)
mkdir -p ~/.gemini/skills
ln -s ~/.claude/skills/vibe-coded-ai ~/.gemini/skills/vibe-coded-ai

The vibe binary on your PATH works identically across all of these tools — only skill discovery differs.

Login

Sign in with your vibe-coded.ai account, however you created it — Google, GitHub, or email and password.

vibe login

It prints a link and a short code and opens your browser. Sign in, check the page shows the same code, and approve; the terminal finishes on its own. Coding agents run it in two steps — vibe login --start prints the link for you to open, then vibe login --finish waits for your approval. Accounts with a password can also use vibe login your@email.com, which reads the password from the terminal so it never enters the conversation.

On success, credentials are written to ~/.vibe-coded/credentials.json with mode 600. The file contains your API token (valid 30 days), your user slug, and the expiry timestamp. Treat it like an SSH private key — don't commit it to git.

When the token expires, re-run vibe login.

First vibe

1. Create and register

mkdir my-app && cd my-app
vibe init --template tools my-app

This registers the vibe on the platform and writes .vibe-coded.json to your project directory. Options:

• --storage kv — KV storage (free). Use --storage sql for a SQL database (Pro or Pro+ plan).
• --title "My App" — Human-readable name (defaults to the slug).
• --template tools — Start from a runnable template. tools is a blank data vibe (notes your AI can add, list, update and delete), tools-sql is the same on SQL (Pro or Pro+), site is a static page with no backend, and tracker, log and journal are closer starting points. Run vibe templates to list them. The template decides storage, and init refuses to overwrite files already in the folder.
• --adopt — Use a vibe you already own from this folder: writes .vibe-coded.json without creating anything.

If the slug is already taken, the command exits with code 2 and prints the existing config as JSON. If it's yours, run vibe init <slug> --adopt to use it from this folder; otherwise pick a new slug.

A slug that reads as a company or an organization role (paypal-login, security-team) is refused with “This slug can't be used — it looks like an organization you're not.” Pick a name that is yours.

2. Develop locally

Edit the worker (worker.js or worker.ts) and, if you want a page, index.html. See Anatomy of a Vibe for the file structure.

vibe dev

vibe dev runs the worker locally with local D1, KV and R2, reloading on save, at http://127.0.0.1:8787. It refuses to start if another program holds the port; pick another with --port. A frontend with a build step (Vite, Vue) isn't built locally, so check it on the preview. vibe dev seed <file.sql> applies SQL to the local database; --reset starts from empty. Run vibe preview when you want to test on the platform.

vibe dev doesn't receive the secrets you stored with vibe secrets. For local runs, put KEY=value lines in a .dev.vars file in the project folder; it is never uploaded.

3. Deploy to preview

When a feature is ready to test on the live platform:

vibe preview

This uploads your source files, triggers a container build (30–60 seconds), and polls until it succeeds or fails. On success it prints the preview URL:

https://p--you--my-app.vibe-coded.ai

deploy is an alias for preview. Don't run it on every file change — use the local dev server for that.

4. Publish to production

Once the preview looks correct:

vibe publish

This deploys the exact build you tested in preview to production; previews never change production on their own. Publishing needs a verified email address: if you signed up with email and password and haven't clicked the link we sent, open your account page and choose “Resend verification email”; previews work either way. It usually prints “Published!” within about 10 seconds. If it takes longer, it says the publish is still in progress and production switches when it finishes (check with vibe status). If a publish fails, the message says whether production was left unchanged or may have been partly updated, in which case run vibe publish again. Your vibe goes live at:

https://you--my-app.vibe-coded.ai

5. Check it with a real call

vibe call calls one MCP tool on the live vibe as you and prints the result, with no browser or connector. Write one record, then read it back:

vibe call add_note '{"text":"first note"}'
vibe call list_notes

Add --preview to call the preview build instead. A tool that exists only in the preview returns “Tool not found” on production until you publish. It exits 1 if the tool returns an error.

Command reference

Run vibe <command> --help for a command's usage. It prints help and exits without running anything.

Command	Purpose	Example
vibe login [email]	Sign in through the browser (or with email and password) and save a 30-day API token. --start / --finish split it into two steps.	vibe login
vibe logout	Remove local credentials	vibe logout
vibe init <slug> [opts]	Register a new vibe and write .vibe-coded.json (--template, --storage kv|sql, --title, --adopt for a vibe you already own)	vibe init --template tools my-app
vibe templates	List runnable starter templates	vibe templates
vibe dev [--port N] [--reset]	Run the worker locally (local D1/KV/R2, reloads on save) at http://127.0.0.1:8787. vibe dev seed <file.sql> applies SQL to the local D1.	vibe dev
vibe preview [--prune|--no-prune]	Upload source, build, and deploy to preview URL (alias: deploy). Uploading and pruning happen in one step: a file you deleted locally stops being served after the next preview. If a prune would remove more than 20 files or over half the vibe, it stops and asks you to re-run with --prune. If the prune fails, the upload is kept, no build runs, and the command exits with an error. Having both worker.js and worker.ts at the root is refused; remove the one you aren't using.	vibe preview
vibe publish	Deploy the tested preview build to production	vibe publish
vibe call <tool> [json] [--preview]	Call one MCP tool on the live vibe as you and print the result	vibe call list_notes
vibe fetch <path> [--preview]	Fetch a deployed page or asset as the owner, including from a private vibe, so you can check a site without a browser. Exits with an error on a 404.	vibe fetch /index.html
vibe connect [<owner>/<slug>] [--name N] [--print|--revoke]	Add this vibe to Claude Code for all your projects: mints a token that can only call this vibe's tools and runs claude mcp add. The connection lasts until your CLI login expires (30 days); re-run it after vibe login to renew; --revoke removes it. For a vibe shared with you, run vibe connect <owner>/<slug>: the token acts with your role and stops if your access is removed.	vibe connect
vibe status [--plan]	Show vibe info, the build that is live on preview and production (e.g. “Preview: build 1741”), and recent builds. --plan prints your account plan.	vibe status
vibe urls	Print app and MCP endpoint URLs for preview and production	vibe urls
vibe logs [build-id]	Show build logs. Omit build ID for the latest build.	vibe logs
vibe settings [--title T]	View settings or update the title	vibe settings --title "My App"
vibe access list	List collaborators. Access changes are completed on the account website.	vibe access list
vibe secrets <sub>	Manage environment secrets — Pro or Pro+ plan required (list, create, update, delete, audit). Write-only: values can't be read back.	vibe secrets create STRIPE_KEY
vibe r2 <sub>	Manage R2 file storage — Pro or Pro+ plan required (upload, download, ls, rm, usage, url). Signed download links last at most 2 minutes, so create one when it's needed rather than sharing it.	vibe r2 upload ./logo.png --key images/logo.png
vibe delete	Print the account website link where deletion is confirmed	vibe delete

Settings and access on the website

Change visibility (private, unlisted, or public) and interaction policy (public, public_read, authenticated, or invite_only; see Sharing & Access) from the vibe's settings panel on the account page. Collaborator grants, role changes, revocation, and permanent deletion are also website-only because they require an interactive login. When you try one of these from the CLI, it prints a link to the right settings panel and exits with an error, so scripts and agents can tell nothing changed.

Access roles are viewer, writer, admin, and owner. A viewer uses the vibe in read mode; writers, admins, and owners can write. Access applies to the whole vibe, not individual tools.

Secret name format

Secret names must match ^[A-Z][A-Z0-9_]{0,63}$ — uppercase letters, digits, and underscores, starting with a letter. Examples: STRIPE_KEY, OPENAI_API_KEY. Secrets are available on Pro and Pro+ plans.

When a secret takes effect

Your worker reads a secret as env.NAME. Creating or rotating one (vibe secrets create / update) reaches the running worker without a rebuild, usually within seconds; allow up to about 30 seconds before relying on the new value. If the vibe has never been built, the secret is stored and the CLI says “Not deployed yet — it reaches your worker on the next vibe preview.” Every preview and publish applies all stored secrets. After vibe secrets delete, a running worker can still read the old value for up to about 30 seconds.

Secrets are only visible when a tool runs in write mode (you, writers and admins). For viewers, and for anonymous callers on a public vibe, env.NAME is undefined, so tools that need a secret should handle that case.

Troubleshooting

Missing credentials

Not signed in. Run: vibe login

Run vibe login to sign in.

Signed up with Google or GitHub

Those accounts have no password, so vibe login your@email.com fails. Run vibe login with no email and sign in through the browser.

Expired token

Your sign-in expired. Run: vibe login

API tokens are valid for 30 days. Re-run vibe login to mint a new one. To revoke tokens immediately, open your account page and choose Revoke all CLI and connection tokens. It signs out every CLI login and every vibe connect token at once. vibe logout removes the local credentials file.

Plan-required errors

SQL (D1) storage is not included in your plan. It comes with Pro or Pro+; KV storage is included on every plan.

SQL storage, file storage, and secrets require a Pro or Pro+ plan. Check your plan with vibe status --plan. See Plans & Billing to upgrade.

Build failed

Build failed. Logs:

Run vibe logs to see the full build output. The error names the file, line and column, for example error: Expected identifier but found ";" at worker.js:31:24. Common causes: a syntax error, missing vite in devDependencies, TypeScript errors, or an incorrect worker entry point. Fix the source and re-run vibe preview.

vibe publish answers EMAIL_NOT_VERIFIED until your email address is verified; the message says how to resend the link. A failed preview can't be published. vibe publish stops with “preview build N failed, so it is not live in preview and cannot be promoted” and tells you to run vibe logs N, fix the error, and preview again.

A tool fails with a server error

When a tool throws, you as the owner see the error message (from vibe call or your own AI client), with credentials, file paths and URLs replaced by [credential], [path] or [redacted]. Anyone else sees only “Internal server error” and a reference id. Reproduce it locally with vibe dev for the full stack trace.

Slug already exists (exit code 2)

vibe init exits with code 2 and prints the existing vibe's config as JSON. If the vibe is yours, run vibe init <slug> --adopt to use it from this folder. Otherwise pick a different slug and re-run vibe init.

File type not accepted

Upload failed for these files:
  init.log: File extension not allowed: .log

vibe preview uploads only these file types, and names any file it skipped: html, htm, css, js, mjs, ts, tsx, jsx, vue, svelte, json, xml, yaml, yml, toml, png, jpg, jpeg, gif, svg, webp, avif, ico, woff, woff2, ttf, eot, otf, md, txt, pdf, lock, plus .gitignore, .npmrc and .nvmrc. Files without an extension are limited to Dockerfile, Makefile, Procfile, Gemfile, Rakefile, LICENSE and CNAME. Any file with password, credential or .secret in its path is refused (Path matches blocked pattern), whatever its type. The other files still upload, but nothing is built until a preview uploads cleanly, and vibe publish refuses with “Your latest upload changed the source but was never built”. Move logs and scratch files out of the project folder, or rename them to an accepted type, and run vibe preview again. Some things are never uploaded: .env files, node_modules, dist, .git, source maps, and agent or editor folders such as .claude, .cursor and .vscode.

Rate limit (429)

Build and deploy operations are rate-limited. If you see a 429 response, wait a moment and retry. Build trigger limits vary by plan (Free: 10/hr, Pro: 30/hr, Pro+: 60/hr per user), with daily ceilings of 50, 150 and 300 builds. Free allows one build in flight at a time. See Plans & Billing.