npx vibex is the Host-family command-line entry. On first run it downloads the Host-family archive for this OS from GitHub Releases, verifies checksums, and starts vibex-server. After a Host is running, the same CLI sends control requests (conversations, workflows, projects, files).

It starts a headless Host and the Web UI in a browser. The desktop GUI ships as a separate installer; see the guide Install the desktop app.

The npm package name is vibex; the current version is 0.1.3. Every example below starts with npx vibex, so it runs without a global vibex install.

Help and version

npx vibex --help / npx vibex help / npx vibex -h: print the top-level usage covering Host start, local Agent install, control commands, and plugin packing. The three forms are equivalent.

npx vibex help serve: print Web UI start usage only. Replace serve with list, install, conversation, workflow, project, workspace, session, file, git, agent, or plugin for that topic. npx vibex conversation --help matches npx vibex help conversation. npx vibex help list and npx vibex help install print the local installer usage.

npx vibex --version / npx vibex -V / npx vibex version: print the CLI version, for example 0.1.3. That version also selects the default Host-family tag v0.1.3.

Starting the Host

• npx vibex: start the Host on loopback 127.0.0.1:17891. For local scripts and a local browser.
• npx vibex serve / npx vibex web: start the Host on LAN interfaces, open the Web UI, and print origins plus the Host token. web is identical to serve.
• npx vibex serve --local: print origins and token and serve the Web UI, bound to loopback only.
• npx vibex serve --port 18080: listen on 18080. The default is 17891.
• npx vibex serve --rotate-token: generate a new Host token, save it, and print it. The previous token fails immediately.
• npx vibex --mcp: start vibex-mcp (the local MCP server agents call). Remaining arguments go to that binary.

Flags combine, for example npx vibex serve --local --port 18080. Details: Start the Host.

Install Agents locally

These commands open the Host data directory, list or install Runtime and ACP, skip HTTP, and leave VIBEX_TOKEN unused. Details: Install Agents locally.

• npx vibex list: list the 13 built-in Agents, plus official ACP Registry entries whose identity is outside the built-in table.
• npx vibex list --refresh: fetch the official Registry snapshot, then print.
• npx vibex list --json: print a JSON array.
• npx vibex install claude_code --yes: install that Agent’s Runtime and ACP into the user environment, skipping the prompt.
• npx vibex install claude_code -y -g: same as the previous line. -g is accepted and has no extra meaning.

Without a terminal, --yes or -y is required. npx vibex agent list still calls a running Host; see file, git, agent.

Control commands

These require a running Host and VIBEX_TOKEN in the environment. VIBEX_URL defaults to http://127.0.0.1:17891. Flags, return values, and examples live on the dedicated pages.

Conversations, see conversation:

• npx vibex conversation create: create a conversation and optionally submit the first message, starting the first turn.
• npx vibex conversation send: send text to an existing conversation. An idle conversation starts a new turn; an in-flight turn queues the text.
• npx vibex conversation steer: append guidance to the in-flight turn. It stays on that turn.
• npx vibex conversation child / npx vibex conversation fork: create a child conversation, usually to delegate to another agent. The two commands are identical.
• npx vibex conversation show / npx vibex conversation output: read the current output projection and turn status. The two commands are identical.
• npx vibex conversation relations: list parent-child relations (delegated children).
• npx vibex conversation wait: poll about once a second until the current turn reaches a terminal status.
• npx vibex conversation cancel: cancel the in-flight turn. Timeline content and files already written stay.

Workflows, see workflow:

• npx vibex workflow validate: validate workflow JSON and report errors. No runnable version is created.
• npx vibex workflow publish: publish an immutable version after validation.
• npx vibex workflow run: start a run from a published version, bound to a workspace.
• npx vibex workflow show: fetch the run, its steps, and its events in one JSON object.
• npx vibex workflow wait: poll run status until a terminal state.
• npx vibex workflow history: read the event stream for incremental sync or debugging.
• npx vibex workflow cancel: stop scheduling new steps and cancel in-flight agent turns.
• npx vibex workflow resume: submit a decision (retry / accept / skip / cancel) when a run sits on approval, review, or a failed step.

Projects, workspaces, and session cards, see project, workspace, session:

• npx vibex project list: list every project on this Host.
• npx vibex project show: read one project, including its repositories.
• npx vibex project create: register a project, optionally binding a repository path.
• npx vibex project delete: delete the project and its conversations and workspace data. Permanent.
• npx vibex workspace list: list workspaces (project root folders or Git worktrees).
• npx vibex workspace show: read one workspace path, branch, and parent project.
• npx vibex session list: list session cards on a workspace.
• npx vibex session show: read one session card.
• npx vibex session create: create a session card by workspace or by project.
• npx vibex session delete: delete a session record.

Files, Git, and agents, see file, git, agent:

• npx vibex file tree: list a directory tree on the Host machine.
• npx vibex file read: read a text file on the Host.
• npx vibex file write: write a file on the Host. This changes disk directly.
• npx vibex git status: read Git status for a workspace repository.
• npx vibex git stage: stage a path inside the workspace.
• npx vibex git commit: commit staged changes.
• npx vibex agent list: list added agents’ auth and enabled state on a running Host. Local install uses npx vibex list / npx vibex install.

Conventions: Control-plane conventions. Token and URL: Connect to a Host.

Other

• npx vibex plugin pack: validate a plugin directory and write a deterministic .vxp. See plugin pack.
• npx vibex review: this entry is outside the Host family and exits with an error.

Next: Install and versions, Start the Host, Connect to a Host.

npx vibex needs Node.js on this machine (npx ships with it). A global vibex install is optional; this documentation always writes npx vibex … so the current npm-resolved package is used.

The first npx vibex, npx vibex serve, npx vibex list, npx vibex install, or npx vibex --mcp run picks a Host-family archive from OS and CPU:

• linux-x64, linux-arm64
• macos-x64, macos-arm64
• windows-x64, windows-arm64

macOS under Rosetta selects macos-arm64. Any other combination exits with Unsupported platform and the supported list.

Download progress prints to stderr. After checksums pass, vibex-server starts (or vibex-mcp for npx vibex --mcp). Later runs for the same tag and platform reuse the cache.

Print the CLI version:

npx vibex --version
npx vibex -V
npx vibex version

The output looks like 0.1.3. That version maps to the default Host-family tag v0.1.3.

Cache and local directory

Downloads land in ~/.vibex/host-family/<tag>/<platform>/. After checksums pass, the tree is extracted and vibex-server / vibex-mcp are marked executable on Unix.

Point the CLI at an already extracted tree to skip download:

export VIBEX_HOST_FAMILY_DIR=/path/to/extracted-family
npx vibex serve --local

That directory must contain SHA256SUMS. Every file listed there is verified. A missing file or a digest mismatch raises Checksum mismatch or Host family is missing vibex-server.

Pinning and mirrors

VIBEX_HOST_FAMILY_TAG=v0.1.3 npx vibex serve --local
VIBEX_DEBUG=1 npx vibex --version

Artifact names: vibex-host-family-<platform>.tar.gz and .tar.gz.sha256. The archive contains vibex-server, vibex-mcp, web/, and plugins/bundled/.

Running the extracted vibex-server with the same flags matches npx vibex. npx additionally sets VIBEX_STATIC_ROOT to the packaged web/ tree so the Web UI static files are served.

Variable meanings and failures: Environment and troubleshooting. Start flags: Start the Host.

The Host process is vibex-server inside the family archive. npx vibex downloads that binary and starts it with the given flags. The default listen address is 127.0.0.1:17891. Projects, conversations, and plugins live in the local data directory; the Host token is stored there as well.

One data directory has one Host at a time. If the desktop app already occupies that directory, quit the desktop app before the commands below.

npx vibex

npx vibex

Starts the Host on loopback and leaves LAN interfaces unbound. Use it for local scripts and opening http://127.0.0.1:17891 on this machine. The token stays in the data directory; the terminal omits the Token block by default. Control commands use the saved token, or VIBEX_SERVER_TOKEN set before start.

This matches running ./vibex-server in an extracted family directory (vibex-server.exe on Windows). npx also sets VIBEX_STATIC_ROOT to packaged web/ so the browser UI is available.

npx vibex serve / npx vibex web

npx vibex serve
npx vibex web

The two commands are identical. web is an alias of serve. The Host listens on every NIC so a phone or another computer on the LAN can connect. After start the terminal prints:

VibeX Host 0.1.3
  http://127.0.0.1:17891
  http://192.168.x.x:17891
Token
  <host-token>

Export the line under Token as VIBEX_TOKEN so control commands can call this Host. Open any printed http://… origin in a browser for the Web UI. Desktop Settings → Remote connection uses the same port and the same token.

Phone QR pairing needs the LAN origin. A 127.0.0.1 QR is unreachable from the phone.

npx vibex serve --local

npx vibex serve --local

Runs the serve start path: print origins and token, serve the Web UI. Binds loopback only. Use it when this machine needs the Web UI and control commands, and the port should stay local.

--local on the command line overrides VIBEX_SERVER_ALLOW_LAN=1.

npx vibex serve --port 18080

npx vibex serve --port 18080
npx vibex serve --port=18080

Listen on 18080. The default is 17891. --port N and --port=N are equivalent. After changing the port, set VIBEX_URL to http://127.0.0.1:18080. Browser URLs use the new port as well. Use this when 17891 is already taken.

A non-numeric port prints invalid --port and exits. A missing value prints missing value for --port.

npx vibex serve --rotate-token

npx vibex serve --rotate-token

Generate a new Host token, write it to the data directory, and print it. Control commands and paired devices that still use the old token fail immediately; they need the new token or a new pairing. Use this after a suspected leak, or to drop every old device.

Rotation changes authentication only. Projects, conversations, and plugins stay in the same data directory.

npx vibex serve --lan

npx vibex serve --lan

Allow listening on every NIC. npx vibex serve already enables LAN; this flag is the explicit form when combining with npx vibex (loopback) or when invoking vibex-server --lan directly.

If both --local and --lan are present, the process binds loopback only.

npx vibex --mcp

npx vibex --mcp

Start vibex-mcp. The CLI strips --mcp and forwards remaining arguments to that binary. That process exposes local MCP tools to agents and has no Web UI. For the UI, use npx vibex or npx vibex serve.

Combined examples

npx vibex serve --local --port 18080
npx vibex serve --rotate-token --port 17891

Environment variables can change defaults without extra flags: VIBEX_SERVER_ALLOW_LAN=1 enables LAN; VIBEX_SERVER_LISTEN=18080 or VIBEX_SERVER_LISTEN=127.0.0.1:18080 overrides the port; VIBEX_SERVER_TOKEN=… sets the token used at start. Full list: Environment and troubleshooting.

Unknown arguments fail parse and exit. npx vibex --help prints start usage. SIGINT (Ctrl+C) or SIGTERM stop the child; Windows uses taskkill /t.

To list Agents and install Runtime and ACP on this machine, use npx vibex list and npx vibex install. No port is bound. See Install Agents locally.

npx vibex list and npx vibex install list Agents and install Runtime and ACP on this machine. They open the same Host data directory (the same SQLite) as npx vibex serve. No port is bound. VIBEX_TOKEN is unused. The HTTP service can stay down.

npx vibex agent list calls a Host that is already running and reads auth and enabled state for members already added. The commands on this page read and write the local Installation lock.

The first run still downloads the Host-family archive when needed, then forwards arguments to vibex-server. npx omits Starting VibeX Host for these utilities.

npx vibex list

List Agents this Host can install. The first group is the 13 built-in Agents. The second group is official ACP Registry entries whose identity sits outside the built-in table.

npx vibex list

The default read uses the Registry snapshot already cached on this machine. If it has never been refreshed, the ACP Registry section prints:

  (refresh with `vibex-server list --refresh`)

Each row has four columns: Agent id, display name, status, component detail. Example:

Built-in
  claude_code   Claude Code     uninstalled   adapter claude + claude-agent-acp
  codex         Codex           ready         adapter codex + codex-acp
  ...
ACP Registry
  some-agent    Some Agent      available     npx

Status comes from the local Installation lock:

• ready: Runtime and ACP are in the lock; npx vibex serve can create a session with that Agent.
• needs_repair: a lock exists and components need repair.
• uninstalled: a built-in identity has no lock yet.
• available: the Registry has the entry; membership / lock are not in place yet.

The last column on a built-in row is topology, for example adapter claude + claude-agent-acp or native …. A Registry row lists distribution kinds: npx, uvx, binary, or a combination.

Pass the Agent id (for example claude_code) to npx vibex install.

npx vibex list --refresh

npx vibex list --refresh

Fetch a snapshot from the official ACP Registry, write it into the Host database, then print the catalog. Use this when a script needs the latest Registry entries. If refresh fails and a cache exists, the terminal prints registry refresh failed; using the cached snapshot and lists the cache. With no cache it fails: ACP Registry is unavailable.

npx vibex list --json

npx vibex list --json
npx vibex list --refresh --json

Print an indented JSON array. Each object has agent_id, display_name, description, group (built_in or registry), status, and detail. --refresh and --json combine.

npx vibex install

Install that Agent’s Runtime and ACP into the user environment. After a successful ACP handshake, write the Installation lock.

npx vibex install claude_code
npx vibex install claude_code --yes
npx vibex install claude_code -y
npx vibex install claude_code -y -g
npx vibex install some-agent --yes

<agent-id> is required and comes from the first column of npx vibex list. A missing id prints Usage: vibex-server install <agent-id> [--yes] and exits non-zero. An unknown id prints unknown Agent …; run vibex-server list.

With a terminal and without --yes, the CLI prints the Plan (component id, distribution kind, source) and asks:

Install these user-environment packages? [y/N]

y / yes continues. Any other answer cancels with installation canceled.

npx vibex install --yes / npx vibex install -y

npx vibex install claude_code --yes
npx vibex install claude_code -y

Skip the prompt and install the Plan. When there is no terminal, --yes or -y is required; otherwise the CLI prints pass --yes to install without a prompt. Use this in CI, pipes, and any non-TTY script.

npx vibex install -g

npx vibex install claude_code -y -g
npx vibex install claude_code --yes --global

-g and --global are accepted and ignored. Install already writes the user environment (the user npm prefix, uv tools, ~/.local/bin). There is no second global/local mode.

What install does

npx vibex install runs these steps:

1. Open the Host data directory (VIBEX_DATA_DIR overrides it) and use the same SQLite as npx vibex serve.
2. A built-in Agent goes straight into the plan. A Registry Agent is added to membership first, then planned.
3. Components already on PATH at a version at least as new as the lock are reused, with Reusing … at …. When the whole plan is already satisfied, it prints Using the user-environment CLI that already matches the locked versions.
4. Remaining components are written into the user environment: npm install -g --prefix …, uv tool install, or a Binary download into ~/.local/bin.
5. Handshake the installed ACP. On success, write the Installation lock and set lifecycle to ready. A success line looks like Installed claude_code runtime … / ACP ….
6. npx vibex serve can then create a session with that Agent.

Missing Node/npm prints npm was not found; install Node.js and npm first. Missing uv prints uv was not found; install uv first. The CLI uses the toolchain already on this machine. A hosted Node stays out of this path.

User-declared Agents are installed from desktop Settings → Agents. A retired identity fails this command.

Calling the binary

npx vibex forwards these arguments to vibex-server. With an extracted Host family you can invoke the binary directly:

vibex-server list
vibex-server list --refresh
vibex-server list --json
vibex-server install claude_code --yes
vibex-server agents list
vibex-server agents install codex
vibex-server agents install claude_code --yes

vibex-server agents list matches vibex-server list. vibex-server agents install matches vibex-server install. On Windows the executable is vibex-server.exe.

Help

npx vibex help list
npx vibex list --help
npx vibex help install
npx vibex install --help

These forms print usage only. The data directory stays closed. The Registry stays untouched.

Common failures

pass --yes to install without a prompt: there is no terminal. Add npx vibex install AGENT_ID --yes.

installation canceled: the confirm prompt was not answered with y / yes.

npm was not found; install Node.js and npm first / uv was not found; install uv first: install that toolchain on this machine, then rerun npx vibex install.

ACP Registry is empty: run npx vibex list --refresh first.

unknown Agent: the id is missing from the built-in table and from the current Registry snapshot. Run npx vibex list or npx vibex list --refresh.

could not open the Host data directory: the data directory could not be created or opened. Check VIBEX_DATA_DIR and disk permissions.

ACP process exited before initialize: the installed ACP failed handshake. Inspect that Agent’s install output, fix it, then run npx vibex install again.

Control commands call a running Host over HTTP:

POST {VIBEX_URL}/api/v1/call/{command}
Authorization: Bearer {VIBEX_TOKEN}
Content-Type: application/json
x-vibex-protocol-version: 1.0

The body is { "operation_id": "<uuid>", "args": { ... } }. On success, stdout prints data. On HTTP error the process exits non-zero and prints code: message.

Start the Host first (npx vibex or npx vibex serve), export the token in the same shell, then run control commands such as npx vibex agent list.

Environment variables

export VIBEX_URL=http://127.0.0.1:17891
export VIBEX_TOKEN='<paste-token>'
npx vibex agent list

Token sources:

1. The Token block from npx vibex serve.
2. Access Token under desktop Settings → Remote connection, for the same Host.
3. The value supplied as VIBEX_SERVER_TOKEN at start.

Keep the token in the environment, the OS keychain, or the Host data directory. Repositories, chat logs, and shell history that will be committed should hold placeholders only. After rotation the previous token fails immediately; point every control command at the new value. Rotation is npx vibex serve --rotate-token.

After a port change, update VIBEX_URL as well. If the Host ran npx vibex serve --port 18080, then export VIBEX_URL=http://127.0.0.1:18080.

Local browser

With npx vibex serve --local or a loopback origin, open http://127.0.0.1:17891 on this machine. Web UI files come from VIBEX_STATIC_ROOT (npx points at packaged web/). Agents, Git, and the terminal still execute on the Host machine.

With plain npx vibex (no serve), the token is omitted from the terminal by default. The local browser can still open the loopback origin; control commands need the token from the data directory or VIBEX_SERVER_TOKEN.

LAN and workstations

npx vibex serve listens on every NIC by default. A browser or another desktop on the same LAN uses the printed LAN origin and token. Phone QR pairing needs LAN enabled; a 127.0.0.1 QR is unreachable from the phone. Pairing presets are in the guide Connect to a Host.

Public access terminates TLS on a reverse proxy, then forwards to the Host port. Set VIBEX_URL to https://host.example.

Occupancy

One data directory has one Host at a time. When vibex-server occupies the directory, the desktop attaches as a client to that URL. When the desktop occupies the directory, another npx vibex fails or conflicts; stop one process first.

While the Host is offline, control commands fail immediately. Offline cache exists only on paired client UIs.

Control commands run after the Host is up. They call the Host over HTTP; agent processes stay on the Host. Finish Start the Host and Connect to a Host, then export VIBEX_TOKEN.

Command shape:

npx vibex <resource> <action> --flag value

Example: npx vibex conversation create --workspace … --agent …. Resources are conversation, workflow, project, workspace, session, file, git, agent. Actions are create, list, show, and so on. Tokens that start with -- are flags. A flag with no value, or whose next token also starts with --, is treated as on. Other flags take the following token as a string. A leftover token without -- raises Unexpected argument.

Help for each resource

These three forms print usage and skip HTTP:

npx vibex conversation --help
npx vibex conversation help
npx vibex conversation -h

Replace conversation with workflow, project, workspace, session, file, git, or agent. Top-level help is npx vibex help. Per-topic help is also npx vibex help conversation.

npx vibex … --json

Print the result as one-line JSON for jq. Without the flag, objects and arrays still print as indented JSON; a bare string prints as-is.

npx vibex agent list --json
npx vibex conversation show --conversation CONV_ID --json

npx vibex … --operation-id

Supply an idempotency key. The default is a generated UUID. When a script retries the same business operation, reuse one --operation-id so the Host treats both calls as one write.

npx vibex conversation send \
  --conversation CONV_ID \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  --text "continue" \
  --operation-id 11111111-1111-1111-1111-111111111111

npx vibex … --timeout

Applies to wait commands only, in seconds, default 600. If the status is still non-terminal, the CLI raises Timed out after 600s.

npx vibex conversation wait --conversation CONV_ID --timeout 120
npx vibex workflow wait --run RUN_ID --timeout 1800

Call contract

Every request carries operation_id. --conversation, --workspace, --agent, --id, and --run take stable Host IDs, usually UUIDs. Obtain IDs with npx vibex project list, npx vibex workspace list, npx vibex agent list, or the matching create, then pass them onward.

A missing required flag raises Missing required --name. An unknown action raises Unknown … action. HTTP failures exit non-zero and print code: message. If the Host is down or VIBEX_URL is wrong, the error comes from the network layer.

Conversation commands operate a persistent dialogue between you and one agent on the Host. A turn is one cycle of “you send a message → the agent finishes answering”. At most one turn is in flight per conversation. The agent and workspace must already exist, and the agent must be enabled and authenticated. Start with npx vibex agent list and npx vibex workspace list to obtain IDs.

A running Host and VIBEX_TOKEN are required. See Connect to a Host.

npx vibex conversation create

Create a conversation and optionally send the first message immediately.

npx vibex conversation create \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  [--title TITLE] \
  [--prompt TEXT]

--workspace is the workspace ID (project root or a Git worktree), required. --agent is the agent’s stable kind, for example claude_code or codex, required. --title is the display name; omit it and the Host may name the conversation from the first message. --prompt is submitted as the first user message and starts the first turn.

The response is the new conversation JSON, including id. Later npx vibex conversation send, npx vibex conversation wait, and npx vibex conversation show take that ID as --conversation.

If the agent is disabled or unauthenticated, the Host rejects create. Enable and sign in under desktop Settings → Agents, then confirm with npx vibex agent list.

npx vibex conversation send

Send text to an existing conversation. An idle conversation starts a new turn. If a turn is already running, the text enters the input queue and runs in order after the current turn ends.

npx vibex conversation send \
  --conversation CONV_ID \
  --workspace WORKSPACE_ID \
  --agent AGENT_ID \
  --text TEXT

All four flags are required. --text is plain text. This command sends text only: no images, attachments, or plugin actions. --workspace and --agent must match the conversation’s original binding.

The response is the submit JSON. Read turn status afterward with npx vibex conversation show or npx vibex conversation wait.

npx vibex conversation steer

Append guidance to the in-flight turn. It belongs to that turn; no new turn is created.

npx vibex conversation steer \
  --conversation CONV_ID \
  --turn TURN_ID \
  --text TEXT

--turn must be the in-flight turn ID, from the turn field of npx vibex conversation show. All three flags are required. If the agent has no steering capability, the Host returns an error; the text stays a steering request and queued input is unchanged.

With no in-flight turn, the Host returns an error. To add work to an idle conversation, use npx vibex conversation send.

npx vibex conversation child / npx vibex conversation fork

Create a child conversation of an existing one, usually for delegation: the parent agent hands part of the work to another agent. npx vibex conversation fork matches npx vibex conversation child.

npx vibex conversation child \
  --parent CONV_ID \
  --agent AGENT_ID \
  [--title TITLE] \
  [--prompt TEXT] \
  [--hidden]

--parent is the parent conversation ID. --agent is the agent for the child. --title and --prompt match npx vibex conversation create. --hidden marks the child invisible (visible=false). Enable Multi-agent collaboration under Settings → Plugins first; otherwise delegation is unavailable.

The response is the child conversation JSON. List relations later with npx vibex conversation relations --conversation CONV_ID.

npx vibex conversation show / npx vibex conversation output

Read the current output projection, including recent messages and turn.status. npx vibex conversation output matches npx vibex conversation show.

npx vibex conversation show --conversation CONV_ID
npx vibex conversation show --conversation CONV_ID --json

--conversation is required. --json prints one line so scripts can read turn.status. Terminal statuses are completed, failed, cancelled, and interrupted.

npx vibex conversation relations

List parent-child relations (delegated children). Use the child IDs with npx vibex conversation show or npx vibex conversation cancel.

npx vibex conversation relations --conversation CONV_ID

--conversation is required. With no children the response is an empty list.

npx vibex conversation wait

Poll the same read as npx vibex conversation show about once a second until turn.status is completed, failed, cancelled, or interrupted.

npx vibex conversation wait --conversation CONV_ID [--timeout 600]

--conversation is required. --timeout is seconds, default 600. Timeout raises Timed out after Ns. The turn may still be running; inspect with npx vibex conversation show, or raise the timeout and wait again.

npx vibex conversation cancel

Cancel the in-flight turn. Timeline content and files already written stay.

npx vibex conversation cancel --conversation CONV_ID [--reason TEXT]

--conversation is required. --reason is optional and stored as the cancel reason. To revert files, use Undo on that turn in the desktop session. With no in-flight turn, the Host returns an error.

Example sequence

export VIBEX_TOKEN='…'
export VIBEX_URL=http://127.0.0.1:17891

npx vibex conversation create \
  --workspace "$WS" \
  --agent claude_code \
  --prompt "List the top-level directory" \
  --json
# read id from the output into CONV_ID

npx vibex conversation wait --conversation "$CONV_ID"
npx vibex conversation show --conversation "$CONV_ID"

Workflow commands operate a step graph: send a JSON source file to the Host for validation, publish an immutable version, then run that version. The file must be a JSON object; its path is --file. The workspace must already exist.

A running Host and VIBEX_TOKEN are required. Graph editing and Studio are in the guide Graph Workflow.

npx vibex workflow validate

Validate only. No runnable version is created. Use it to check graph structure, dependencies, and step contracts before publish. Failures print the Host error code.

npx vibex workflow validate --file path/to/graph.json

--file is required and must be a JSON file readable on this machine. The contents are sent as the definition. An invalid path or unparsable JSON fails in the CLI before the HTTP call.

npx vibex workflow publish

After validation, create an immutable workflow definition version. Later edits to the source file affect the next publish only; runs already started stay bound to this version.

npx vibex workflow publish --file path/to/graph.json [--definition-id ID]

--file is required. --definition-id binds an existing workflow identity for a new version; omit it and the Host allocates a new identity. Pass the returned version ID to npx vibex workflow run --version.

npx vibex workflow run

Start a run from a published version, bound to a workspace.

npx vibex workflow run \
  --version VERSION_ID \
  --workspace WORKSPACE_ID \
  [--input input.json] \
  [--policy policy.json]

--version and --workspace are required. --input defaults to {} and must be a local JSON file. --policy defaults to empty and overrides completion policy. The response is the run object; store id for npx vibex workflow show, npx vibex workflow wait, and npx vibex workflow cancel.

An unpublished source file cannot be run. Publish first with npx vibex workflow publish.

npx vibex workflow show

Fetch the run, its steps, and events (from sequence 0, up to 1000) and print them as one JSON object. Use it to see a stuck step and a waiting approval.

npx vibex workflow show --run RUN_ID
npx vibex workflow show --run RUN_ID --json

--run is required. The object contains run, steps, and events. Step IDs come from steps and go to npx vibex workflow resume --step.

npx vibex workflow wait

Poll this run’s status until it reaches completed, failed, cancelled, interrupted, or the timeout.

npx vibex workflow wait --run RUN_ID [--timeout 600]

--run is required. --timeout defaults to 600 seconds. After timeout, inspect the current step with npx vibex workflow show. A run sitting on approval is still non-terminal; wait continues until timeout or someone runs npx vibex workflow resume.

npx vibex workflow history

Read the event stream for incremental sync or debugging.

npx vibex workflow history --run RUN_ID [--after N] [--limit 1000]

--run is required. --after is the last processed sequence, default 0. --limit defaults to 1000. A script can remember the last sequence and pass --after to fetch only new events.

npx vibex workflow cancel

Stop scheduling new steps and cancel in-flight agent turns. File changes already made stay in the workspace.

npx vibex workflow cancel --run RUN_ID [--reason TEXT]

--run is required. --reason is optional. Cancelling an already finished run returns a Host error.

npx vibex workflow resume

When a run sits on approval, review, or a failed step, submit a human decision to continue.

npx vibex workflow resume \
  --run RUN_ID \
  --decision retry|accept|skip|cancel \
  [--step STEP_ID] \
  [--output output.json] \
  [--reason TEXT]

--run and --decision are required. --decision values:

• retry: run that step again; --step required
• skip: skip that step; --step required
• accept: accept the step’s candidate output; --step required; with --output, that JSON is the accepted content
• cancel: end the whole run; optional --reason; --step omitted

Step IDs come from the steps list of npx vibex workflow show. A missing required --step raises Missing required --step.

These commands manage projects (engineering directories), workspaces (the directory tree a conversation reads and writes), and session lists on the Host. Paths are paths on the Host machine. A running Host and VIBEX_TOKEN are required.

A project registers an engineering tree. A workspace is the directory bound to a conversation (project root or a Git worktree). A session card is a board entry. Dialogue content and turns use the conversation commands.

npx vibex project list

List every project on this Host.

npx vibex project list
npx vibex project list --json

No extra flags. The response is an array of projects, each with id, name, repository paths, and related fields. Use id with npx vibex project show, npx vibex project delete, and npx vibex session create --project.

npx vibex project show

Read one project, including its repositories (the git repo IDs used as --repo on npx vibex git).

npx vibex project show --id PROJECT_ID

--id is required. An unknown ID returns a Host error.

npx vibex project create

Register a project on the Host. With only a name, the Host creates or binds a directory by its own rules. With --path, that path is registered as a repository.

npx vibex project create --name demo
npx vibex project create --name demo --path /home/you/src/demo

--name is required. --path is optional and must be a Git directory the Host can access, or a directory it will initialize. When --path is set, the repository display_name matches the project name and git_repo_path is that path. The response is the new project JSON; store id.

The path is on the Host machine. Running the CLI on another computer still points at the Host’s filesystem.

npx vibex project delete

Delete the project and its conversations and workspace data. Permanent.

npx vibex project delete --id PROJECT_ID

--id is required. An in-progress conversation may cause the delete to fail; the Host returns the error. Confirm the target with npx vibex project show first. The Host response records what happens to the Git repository on disk.

npx vibex workspace list

List workspaces. A workspace is the directory bound to a conversation: the project root folder, or a Git worktree cut from that folder.

npx vibex workspace list
npx vibex workspace list --project PROJECT_ID

Without --project, every workspace on the Host is listed. With --project, only that project’s trees. Each item includes a workspace id, used as --workspace on npx vibex conversation create and npx vibex session list.

New worktrees are created in the desktop New session → New workspace flow, then discovered with this command. This CLI has no separate “create worktree” action.

npx vibex workspace show

Read one workspace’s path, branch, and parent project.

npx vibex workspace show --id WORKSPACE_ID

--id is required. Use it to confirm which directory tree a conversation will read and write.

npx vibex session list

List session cards on a workspace (the board entries).

npx vibex session list --workspace WORKSPACE_ID

--workspace is required. The response includes session ID, title, agent, and status. Missing --workspace raises Missing required --workspace.

npx vibex session show

Read one session card.

npx vibex session show --id SESSION_ID

--id is required. Difference from npx vibex conversation show: this command is the board/catalog record; npx vibex conversation show is dialogue output and turn status. In most cases the two IDs name the same conversation; trust the returned JSON.

npx vibex session create

Create a session card. Two shapes.

By workspace (the workspace must already exist):

npx vibex session create \
  --workspace WORKSPACE_ID \
  [--agent AGENT_ID] \
  [--title TITLE] \
  [--prompt TEXT]

By project (the Host may pick the project’s default workspace):

npx vibex session create \
  --project PROJECT_ID \
  [--workspace WORKSPACE_ID] \
  [--agent AGENT_ID] \
  [--title TITLE] \
  [--prompt TEXT]

--title, --prompt, and --agent are all optional. To bind an agent and send the first message immediately, npx vibex conversation create is the direct path. This command fits creating a board entry from a project catalog. The ID in the JSON can be passed to npx vibex conversation send.

With --project, the project-create API is used and --workspace may be omitted. With only --workspace (no --project), the workspace-create API is used. Missing both raises Missing required --workspace.

npx vibex session delete

Delete a session record. The Host decides whether an in-progress session can be removed; failures print an error.

npx vibex session delete --id SESSION_ID

--id is required. This removes the Host session record. The workspace directory and Git history stay on disk.

These commands read and write files on the Host machine, stage and commit Git changes, and list agents. Paths are resolved by the Host and belong to that machine. A caller with the Host token is authorized; production scripts keep paths inside a known workspace. A running Host and VIBEX_TOKEN are required.

npx vibex file tree

List the file tree under a directory.

npx vibex file tree --path /home/you/src/demo
npx vibex file tree --path /home/you/src/demo --depth 2

--path is required and is an absolute path on the Host. --depth is how many levels to expand, default 3, and must be a number. Use it in scripts to confirm layout before npx vibex file read / npx vibex file write. A missing path returns a Host error.

npx vibex file read

Read a file’s text and print it.

npx vibex file read --path /home/you/src/demo/README.md

--path is required. Large or binary files may be truncated or rejected; the error code is in the response. Default print is the text; with --json the whole contents are a JSON string.

npx vibex file write

Write contents to a file on the Host. Supply --text or --file; if both are present, --text is used.

npx vibex file write --path /home/you/src/demo/notes.md --text "hello"
npx vibex file write --path /home/you/src/demo/notes.md --file ./local.md

--path is required. --file points at a local file on the machine running the CLI; contents are read as UTF-8 and sent to the Host. This writes disk directly, with no agent permission prompt. Missing both content sources raises Missing required --file.

npx vibex git status

Read Git status (changed files, branch, and related fields) for a workspace repository.

npx vibex git status --workspace WORKSPACE_ID --repo REPO_ID

--workspace and --repo are required. --repo comes from the repository list in npx vibex project show --id PROJECT_ID. Exact fields are those in the JSON.

npx vibex git stage

Stage one path inside the workspace.

npx vibex git stage --workspace WORKSPACE_ID --repo REPO_ID --path relative/path.ts

All three flags are required. --path is relative to the workspace. One path per call; repeat the command for more files.

npx vibex git commit

Create a commit from staged changes.

npx vibex git commit --workspace WORKSPACE_ID --repo REPO_ID --message "describe this change"

--workspace, --repo, and --message are required. An empty index returns a Host error. Push, pull requests, and rebase stay in the desktop Git panel, or an agent performs them after approval. This CLI stops at commit.

npx vibex agent list

List agents added to the Host, with install, auth, and enabled status.

npx vibex agent list
npx vibex agent list --json

No extra flags. The stable kind in the array (for example claude_code) is the value for --agent. Disabled or unauthenticated rows still appear; npx vibex conversation create against them is rejected. Enable and sign in under desktop Settings → Agents first.

This command needs a running Host and VIBEX_TOKEN. To list installable Agents and write Runtime and ACP on this machine, use npx vibex list and npx vibex install; HTTP can stay down. See Install Agents locally. Sign-in remains desktop Settings → Agents.

The plugin surface on npx vibex is pack only: take a v4 plugin directory and write a deterministic .vxp for someone else to install via desktop Import plugin.

Authoring, linked debug, and hot reload use vibex-plugin (source at packages/plugin-cli). See Development workflow.

npx vibex plugin pack

npx vibex plugin pack
npx vibex plugin pack .
npx vibex plugin pack ./my-plugin
npx vibex plugin pack ./my-plugin --output ./dist/office.vxp

The first argument is the plugin root; it defaults to the current directory. That directory must contain .vibex-plugin/plugin.json, README.md, and the rest of the layout in Package layout.

Order of work: full validation first (summary, schema, content index, integration refs). Failures print each code: message line and exit. On success a .vxp is written and stdout prints two lines:

/absolute/path/dist/<plugin-id>-<version>.vxp
sha256:<packageDigest>

--output sets the result file. The default is dist/<plugin-id>-<version>.vxp inside the plugin directory.

The same source packed twice with npx vibex plugin pack should yield the same sha256. Published npx packages embed plugin-cli under plugin-cli/. A missing directory raises VibeX Plugin CLI is unavailable; reinstall or upgrade the vibex npm package.

Unknown subcommands such as npx vibex plugin init raise Unknown plugin command. Init and linked debug belong to vibex-plugin, not npx vibex.

npx vibex plugin --help / npx vibex help plugin

npx vibex plugin --help
npx vibex help plugin

Prints Usage: vibex plugin pack [dir] [--output file.vxp] and skips the Host.

Variables read when starting the Host

These apply when running npx vibex or npx vibex serve.

VIBEX_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.

VIBEX_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/Xircth/VibeX/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.

VIBEX_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, vibex-server, web/). When set, download is skipped.

VIBEX_GITHUB_REPO: GitHub owner/name, default Xircth/VibeX.

VIBEX_STATIC_ROOT: Web UI static file root. npx vibex points it at packaged web/. When you start vibex-server yourself and need the browser UI, point this at a web/ tree.

VIBEX_SERVER_ALLOW_LAN: set to 1 and even npx vibex (loopback start) listens on every NIC. npx vibex serve --local on the command line still binds loopback only.

VIBEX_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.

VIBEX_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.

VIBEX_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.

VIBEX_DATA_DIR: Host data directory. npx vibex serve, npx vibex list, and npx vibex install share this SQLite. Unset, the machine default data directory is used.

Variables read by control commands

VIBEX_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.

VIBEX_TOKEN: Bearer token, required. Missing it raises VIBEX_TOKEN is required. Copy it from the Token block of npx vibex serve, or from desktop Settings → Remote connection.

Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.

Common failures

Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.

Host family download failed: network, firewall, or a bad tag. Check VIBEX_HOST_FAMILY_TAG and open the Release page for vibex-host-family-<platform>.tar.gz.

Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.vibex/host-family/<tag>/ and retry, or point at a verified VIBEX_HOST_FAMILY_DIR.

Host family is missing vibex-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.

VIBEX_TOKEN is required: the token is unset. Run npx vibex serve and copy from the terminal, or copy from the desktop remote-connection page.

Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx vibex conversation show / npx vibex workflow show.

Missing required --x: a required flag is absent. Compare with npx vibex help conversation (or the matching resource).

Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx vibex plugin pack again.

Port in use: switch to npx vibex serve --port 18080, or stop the process holding 17891.

pass --yes to install without a prompt: npx vibex install ran without a terminal and without --yes. Use npx vibex install AGENT_ID --yes.

npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx vibex install. Full write-up: Install Agents locally.

npx vibex help
npx vibex --version