vibe CLI

vibe is the command-line client for a Vibery Station and its Gateway. It shows your station status, jumps between docked projects and crew worktrees, keeps favorites, renders the daily briefing, and tags files, all from the terminal.

• npm package: @vibery/vibe-cli
• Binary: vibe (plus the vgo alias once shell integration is loaded)
• Requires Node.js 22.22.2 or newer

Inside the hosted Vibery terminal, vibe is already installed and authenticated. Skip to Commands.

Install

npm install --global @vibery/vibe-cli
vibe --version

Version note. npm currently serves 0.1.1. Finding the desktop app automatically (via gateway.json), the vibery://pair link, the Linux browser opener and the Windows %APPDATA% lookup need 0.1.2, which is not published yet. Until then, set the two URLs from the app's gateway.json (see File locations) before vibe login:

export VIBE_GATEWAY_URL=ws://127.0.0.1:<port>
export VIBE_WEB_URL=http://127.0.0.1:<port>

Copy

Or install 0.1.2 from source.

npm is the only supported install channel.

Load shell integration so vibe go can change your current directory (a child process cannot cd its parent shell, so a small wrapper function does it):

# zsh
eval "$(vibe shell-init zsh)"
# bash
eval "$(vibe shell-init bash)"

Add the line for your shell to ~/.zshrc or ~/.bashrc once it works. It also defines the vgo alias for vibe go.

Quickstart

1. Open the Vibery desktop app. Running a Station from a source checkout instead? See Running from a source checkout.

2. Pair this CLI:

   vibe login
   

   Copy

   vibe login checks that the Gateway and the Station web app are reachable, then starts a pairing request. It opens the approval page, /cli/pair on the Station web app (or the Vibery window via a vibery://pair link when the desktop app is running). Approve the named client there within 10 minutes. After that the request expires and you must run vibe login again.

3. Check it worked:

   vibe whoami
   vibe doctor
   

   Copy

Use a named profile when one machine needs more than one paired client:

vibe login --profile work --name "Work laptop"
vibe --profile work whoami

Token lifetime

Tokens issued by vibe login pairing have a 30-day sliding expiry.

Successful Gateway authentication refreshes the expiry to 30 days from that use. Refresh writes are throttled, so not every command updates the expiry. After roughly 30 days of inactivity, or if the token is revoked, re-run vibe login (add --profile NAME if you use one). Expired or revoked tokens cannot be refreshed.

This sliding expiry applies only to pairing-issued client tokens, not Settings or /auth/cli-token tokens, hosted-terminal tokens, browser/chat-proxy tokens, or legacy tokens without the pairing marker. Those keep their fixed expiry.

The hosted Vibery terminal gets a fresh token every time it starts a shell, so you never need to log in there.

Commands

Global option: --profile NAME (or --profile=NAME) selects a paired client profile for one command. Names are 1 to 64 letters, numbers, dots, underscores, or hyphens. When --profile is given, VIBE_TOKEN and VIBE_TOKEN_FILE are ignored for that command, so an inherited token cannot sign you in as someone else.

Environment variables

Token resolution order: VIBE_TOKEN, then VIBE_TOKEN_FILE, then the paired profile file. With no token, Gateway commands fail with Unauthorized.

Gateway URL resolution order: VIBE_GATEWAY_URL, VIBERY_GATEWAY_URL, the running Station's gateway.json, then ws://127.0.0.1:8080. The web URL follows the same pattern: --web-url (login only), VIBE_WEB_URL, gateway.json, then http://127.0.0.1:3000.

File locations

Data-root resolution order (only existing directories count; the first match wins for gateway.json and vibe brief):

1. $VIBE_DATA_ROOT
2. $VIBERY_DATA_ROOT
3. /data (inside the backend container)
4. %APPDATA%\vibery\data (Windows desktop installs)
5. ~/.vibery/data (macOS and Linux desktop installs, and vibe gateway start)

Hosted Gateway

The production Gateway is wss://gateway.vibery.gg, and the web app is https://vibery.gg.

What works today:

• Hosted Vibery terminal: vibe is preinstalled and VIBE_GATEWAY_URL and VIBE_TOKEN are set for you. Run commands directly.

• Pointing at the hosted Gateway with a token you already have:

  export VIBE_GATEWAY_URL=wss://gateway.vibery.gg
  export VIBE_TOKEN_FILE=~/path/to/token
  vibe whoami
  

  Copy

What does not work today: vibe login against the hosted Gateway. The Gateway only accepts pairing requests that come from the same machine (loopback), and requests through the gateway.vibery.gg proxy are refused with CLI pairing start is loopback-only. Pair against a local or desktop Station instead.

Troubleshooting

Unauthorized, or a command fails after working earlier. Your paired token has expired or was revoked. Run vibe login again (add --profile NAME if you use one). Inside the hosted terminal, open a new terminal tab to get a fresh token.

Cannot reach the Vibery Gateway at .... Nothing is listening at that URL. For a local Station, open the desktop app (or run vibe gateway start from a source checkout). Otherwise check VIBE_GATEWAY_URL. vibe whoami and vibe doctor show which URL is in use, and curl http://127.0.0.1:8080/health (with your host) checks the backend directly.

Cannot reach the Station web app at .... vibe login also needs the web app. Open the desktop app, or pass the web app URL with vibe login --web-url URL.

No browser opens on headless Linux. vibe login uses xdg-open. Without it you will see Could not open a browser automatically. Open the printed Approval URL in any browser that is signed in to the Station, and approve within 10 minutes.

CLI pairing expired before approval. The 10-minute window passed. Run vibe login again.

Windows. Paired profiles, and the desktop Station's data root (where its gateway.json lives):

%USERPROFILE%\.vibery\vibe\clients\
%APPDATA%\vibery\data

vibe go prints a path but does not change directory. Shell integration is not loaded. Run eval "$(vibe shell-init zsh)" (or bash). vibe doctor warns when it is missing.

vibe update says the CLI is not npm-managed. Reinstall with npm install --global @vibery/vibe-cli.

Running from a source checkout

For contributors with access to the Vibery repo. Run these from the repo root.

Start a local Station in two terminals:

# terminal 1: local backend, loopback only
vibe gateway start

# terminal 2: Station web app
npm --prefix vibery-ui-web run dev

Then continue with step 2 of the Quickstart.

Install 0.1.2 from source

npm ci --ignore-scripts \
  --include-workspace-root=false \
  --workspace @vibery/vibe-cli \
  --workspace @vibery-llc/sacred-markdown
npm run build --workspace @vibery/vibe-cli
node scripts/stage-vibe-cli-package.mjs
npm install --global ./packages/vibery-cli/.publish