CLI Reference

Install once, publish anywhere. The vibes CLI wraps the It Just Vibes REST API — authenticate with your API key, then publish, share, find, and manage widgets from any shell or AI tool.

npm install -g @itjustvibes/cli

Global Flags

These flags are accepted by every command. Credential precedence: --key flag › IJV_API_KEY env › saved config file.

Flag	Description
`--key <key>, -k`	API key — overrides IJV_API_KEY env and the saved config file.
`--json`	Machine-readable JSON output (no color). Error shape: { ok, error, code, exit }.
`--no-color`	Disable ANSI color output (also disabled when NO_COLOR env is set or stdout is not a TTY).
`--help, -h`	Show help for the current command.
`--version, -v`	Print the CLI version and exit 0.

publish

vibes publish

Publish a widget file to itjustvibes.com. Authenticated (Bearer key) uploads to your account; unauthenticated uploads as a guest and returns a claim URL to make it yours.

Usage

vibes publish <file> [flags]

Flags

Flag	Type	Default	Description
`--title <title>`	`string`	—	Widget display title. Defaults to the file basename (without extension).
`--category <category>`	`string`	`misc`	Widget category. Defaults to "misc".
`--key <key>, -k`	`string`	—	API key (overrides IJV_API_KEY env and config file).
`--json`	`boolean`	—	Output machine-readable JSON: { ok, url, slug, claim_url }.

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Widget published successfully.
`1`	`ERROR`	Network failure, server error, or 413 file-too-large.
`2`	`USAGE`	File not found or bad arguments.
`4`	`PERMISSION`	API key rejected (401/403).

Examples

# Publish with your API key (set via vibes login or IJV_API_KEY env)
vibes publish my-widget.html
# => Published. URL: https://itjustvibes.com/w/my-widget

vibes share

Update the visibility of a widget you own. Requires an API key — guests cannot change visibility.

Usage

vibes share <slug> --visibility <value> [flags]

Flags

Flag	Type	Default	Description
`--visibility <value>`	`string`	—	New visibility: public or private_sole (only you). Note: private_group is not yet supported — group targeting is deferred.req
`--key <key>, -k`	`string`	—	API key (overrides IJV_API_KEY env and config file).
`--json`	`boolean`	—	Output machine-readable JSON: { ok, slug, visibility }.

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Visibility updated.
`2`	`USAGE`	Missing --visibility or invalid value.
`4`	`PERMISSION`	No API key, 401, 403 (not owner), or 404.

Examples

vibes share my-widget --visibility public

find

vibes find

Search the widget catalogue. Returns a paginated table of matching widgets with slug, title, author, and vote score.

Usage

vibes find <query> [flags]

Flags

Flag	Type	Default	Description
`--category <category>`	`string`	—	Filter by category.
`--author <handle>`	`string`	—	Filter by author handle.
`--limit <n>`	`number`	—	Maximum results to return.
`--cursor <cursor>`	`string`	—	Pagination cursor from a previous find result.
`--key <key>, -k`	`string`	—	API key for authenticated results.
`--json`	`boolean`	—	Output raw JSON array of widgets.

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Search completed (even if zero results).
`1`	`ERROR`	Network or server error.
`2`	`USAGE`	Bad arguments or parameters.
`4`	`PERMISSION`	API key rejected (401/403).

Examples

vibes find "dark clock"
#   SLUG           TITLE            AUTHOR    VOTES
#   dark-clock     Dark Clock       @handle   42

get

vibes get

Fetch full widget metadata and source code. Human output includes title, author, visibility, URL, created date, and source code. Use --json for machine consumption.

Usage

vibes get <slug> [flags]

Flags

Flag	Type	Default	Description
`--key <key>, -k`	`string`	—	API key to access private widgets you own.
`--json`	`boolean`	—	Output JSON: { slug, title, author, visibility, url, source_code, created_at }.

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Widget fetched.
`1`	`ERROR`	Network or server error (5xx).
`4`	`PERMISSION`	404 (not found or private) or 401/403.

Examples

vibes get my-widget
# Title:      My Widget
# Author:     @handle
# Visibility: public
# URL:        https://itjustvibes.com/w/my-widget

export

vibes export

Download a widget's source code to a file or print to stdout. Uses the same endpoint as get — no additional API call needed.

Usage

vibes export <slug> [flags]

Flags

Flag	Type	Default	Description
`--output <file>, -o`	`string`	—	Destination file path. Prints to stdout when omitted. URL-like paths are rejected (SSRF guard).
`--key <key>, -k`	`string`	—	API key to export private widgets you own.

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Source code exported.
`1`	`ERROR`	Network or server error.
`2`	`USAGE`	URL-like --output path rejected (use a local file path).
`4`	`PERMISSION`	404 (not found or private) or 401/403.

Examples

vibes export my-widget --output my-widget.html

login

vibes login

Save your API key to the local config file. Validates the key against /api/v1/me before saving. Keys are stored with 0o600 permissions in the XDG config directory.

Usage

vibes login --key <key>

Flags

Flag	Type	Default	Description
`--key <key>, -k`	`string`	—	Your API key (starts with jb_live_). Generate one from account settings.req

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	Key validated and saved.
`4`	`PERMISSION`	Key rejected (401) — check the key and try again.

Examples

Shell

vibes login --key jb_live_XXXXXXXXXXXX
# => Authenticated as @yourhandle
# => Key saved to ~/.config/itjustvibes/config.json

mcp

vibes mcp

MCP connector utilities. Two subcommands: mcp install writes the hosted MCP connector config to .mcp.json (read-merge-write, never clobbers sibling keys); mcp serve starts a stdio MCP proxy forwarding JSON-RPC + Bearer to the remote /api/mcp endpoint.

Usage

vibes mcp <install|serve> [flags]

Flags

Flag	Type	Default	Description
`--key <key>, -k`	`string`	—	API key used by mcp serve as the Bearer token. Required for mcp serve; optional for mcp install (warns without a key).

Exit Codes

Code	Name	Meaning
`0`	`SUCCESS`	mcp install wrote .mcp.json.
`1`	`ERROR`	Malformed existing .mcp.json (mcp install aborts rather than clobber).
`4`	`PERMISSION`	No API key configured (mcp serve exits before opening transport).

Examples

vibes mcp install
# => MCP connector written to .mcp.json
# =>   URL: https://www.itjustvibes.com/api/mcp

Exit Codes

All commands use these four exit codes consistently. Use --json for machine-readable exit payloads: { ok, error, code, exit }.

Code	Name	Meaning
`0`	`SUCCESS`	Command completed successfully.
`1`	`ERROR`	Generic runtime error (network failure, unexpected server error, parse error).
`2`	`USAGE`	Bad arguments, unknown flag, or missing required argument.
`4`	`PERMISSION`	Authentication failed (401), insufficient scope (403), or no API key configured.

CLI flags and examples in this page are kept in lockstep with the SDK prompt coupling rule in apps/web/lib/sdk-prompts.ts. Update CLI_SKILL, SKILL.md, and this page together when the CLI surface changes.