Weavz CLI

Install and use the Weavz CLI for terminals, SSH sessions, containers, cloud IDEs, and coding agents.

Weavz CLI

The Weavz CLI lets developers, operators, and coding agents operate a connected Weavz workspace from a terminal. It signs in with device OAuth and uses the hosted Weavz MCP connector at /mcp/weavz.

Use it to inspect workspace context, manage connected apps, discover actions, validate inputs, execute a single action, or run a Code Mode workflow from a terminal. Use the SDKs or REST API when your product backend needs to provision workspaces, end users, connect links, MCP servers, triggers, partials, or approval policies with a wvz_... API key.

Install

The CLI requires Node.js 22.13 or newer when installed through npm or the curl installer.

bash

brew install weavz/tap/weavz

bash

curl -fsSL https://get.weavz.io/cli | sh
export PATH="$HOME/.weavz/bin:$PATH"

bash

npm install -g @weavz-io/cli

Run without a persistent install:

bash

npx -y @weavz-io/cli login

bash

weavz login

The CLI prints a short code and a browser URL. Open the URL in any browser, sign in to Weavz, choose or create a workspace, verify the code, and approve the CLI. This works from SSH sessions, containers, cloud IDEs, and agent runtimes because the browser does not need to run on the same machine.

Useful login options:

bash

weavz login --no-open
weavz login --open
weavz login --profile staging
weavz login --host https://platform.weavz.io

CLI login creates credentials for the Weavz MCP connector. Those credentials are not wvz_... REST API keys. Use WEAVZ_API_KEY with the SDKs or REST API for backend automation.

Common Flow

Start by confirming the workspace and available apps:

bash

weavz status
weavz agent context --json

Search for an action, inspect its input contract, validate input, then execute:

bash

weavz actions search "send slack message" --json
weavz actions info support_slack.send_channel_message --json
weavz actions validate support_slack.send_channel_message \
  --set channel=C123456 \
  --set text="The build is green." \
  --json
weavz run support_slack.send_channel_message \
  --set channel=C123456 \
  --set text="The build is green." \
  --idempotency-key build-green-20260624 \
  --json

For side effects, use --dry-run or --explain before execution:

bash

weavz run customer_gmail.send_email --input @email.json --dry-run --json
weavz run customer_gmail.send_email --input @email.json --explain

What You Can Do

Command	Purpose
`weavz login`	Start device-code sign-in for the hosted MCP connector
`weavz logout`	Remove a local profile
`weavz status` / `weavz whoami`	Show profile, host, workspace, MCP server, app count, tool count, and pending approvals
`weavz agent context`	Print an agent-ready workspace summary with matching actions and recovery commands
`weavz agent skill`	Print a reusable instruction file for Codex, Claude, or a generic coding agent
`weavz apps`	List, search, add, connect, disconnect, remove, or open dashboard for workspace apps
`weavz actions`	List, search, inspect, resolve options, validate, or execute exact `alias.action` calls
`weavz run`	Alias for direct action execution with input flags, dry-run, idempotency, approval wait, and JSON output
`weavz tools`	List MCP tools, search Code Mode actions, or read typed APIs for aliases
`weavz exec`	Run a Code Mode JavaScript workflow through `weavz_execute`

App and Action Management

Apps are workspace integrations. Each one has an alias such as team_slack, customer_gmail, or billing_stripe. The alias is the stable name agents use in Code Mode and direct CLI action calls.

bash

weavz apps list --json
weavz apps search gmail --json
weavz apps add gmail --alias customer_gmail --json
weavz apps connect customer_gmail
weavz apps remove customer_gmail --confirm

Action ids use alias.actionName. Natural language is only for search:

bash

weavz actions search "create github issue" --json
weavz actions info engineering_github.create_issue --json
weavz actions options support_slack.send_channel_message channel --search eng --json

Inputs can come from JSON, files, stdin, scalar path updates, or JSON path updates:

bash

weavz run customer_gmail.send_email --input '{"to":"[email protected]","subject":"Hi","body":"Hello"}'
weavz run customer_gmail.send_email --input @email.json --json
cat email.json | weavz run customer_gmail.send_email --input - --json
weavz run sheets.add_row --set-json 'values=["Acme",42,true]' --json
weavz run crm.create_contact --set address.city=Berlin --set tags[]=lead --set tags[]=trial --json

If a Human Gate pauses execution, show the approval URL and retry with the same input and idempotency key after approval. Add --wait-for-approval-seconds 30 when the CLI should poll briefly:

bash

weavz run customer_gmail.send_email \
  --input @email.json \
  --idempotency-key email-001 \
  --wait-for-approval-seconds 30 \
  --json

Code Mode Workflows

Use weavz exec when one workflow needs multiple app calls, loops, joins, transformations, Filesystem, State KV, or Sandbox-backed work. For one known action, prefer weavz run.

bash

weavz exec 'return { ok: true, now: new Date().toISOString() }'

bash

weavz exec --json <<'JS'
const messages = await weavz.support_slack.search_messages({
  query: "escalation after:2026-06-01"
})
 
return {
  count: messages.length,
  sample: messages.slice(0, 5)
}
JS

Before writing Code Mode scripts against an unfamiliar alias, inspect the API:

bash

weavz tools search "slack messages" --json
weavz tools api support_slack --detail signatures --json

Profiles and Environment

Setting	Use
`--profile <name>` / `WEAVZ_PROFILE`	Keep separate local credentials for production, staging, or local development
`--host <url>` / `WEAVZ_HOST`	Point the CLI at a specific Weavz host
`--timeout <seconds>` / `WEAVZ_TIMEOUT_SECONDS`	Set MCP request timeout
`WEAVZ_CONFIG_DIR`	Store CLI credentials in a specific directory for tests, containers, or temporary environments

For CI automation, prefer scoped Weavz API keys and the SDKs. The CLI login flow is designed for interactive users and agents acting with user approval.

Next Steps

TypeScript SDK — backend provisioning with generated TypeScript action inputs
Python SDK — backend and agent-framework automation with generated Pydantic models
MCP Code Mode — the agent runtime model behind weavz exec
Weavz MCP App — connect Weavz directly from hosted MCP clients
Human Gates — approval behavior for CLI, SDK, API, MCP, Playground, and trigger execution