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