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