Willow CLI
willow is the Willow command-line tool. Use it to sign in, browse the MCP tools you have access to, and call them from a terminal, a script, or a CI/CD pipeline. It also installs a skill into the AI agents on your machine so they can find and call your tools through the CLI on their own.
This reference covers @willowai/cli version 0.2.5.
The Willow CLI replaces the earlier MCP-S CLI (@mcp-s/cli, command mcp-s-cli). The Willow CLI option in the Connect MCP dialog now installs @willowai/cli.
Install
Requires Node.js 18 or later.
npm install -g @willowai/cli
Quick setup
Select Willow CLI in the Connect MCP dialog. The dialog shows commands to install, initialize, and sign in. To use the exact gateway shown in Connect MCP, initialize with --base-url and the full MCP URL, including /mcp:
npm install -g @willowai/cli
willow init --base-url https://your-org.withwillow.ai/mcp
willow auth login
willow init writes your configuration and installs the Willow skill into any AI agents it detects (Cursor, Claude Code, Codex, and others). Run it once per machine. willow auth login opens your browser to sign in.
The URL may use a region-specific or custom domain. Copy your organization's exact URL. If you already initialized with --org, you can set the full URL before signing in:
willow config set baseUrl https://your-org.withwillow.ai/mcp
willow auth login
If you open the dialog with Use on a server's card, turn on Scope to this MCP only to limit the CLI to that server. The dialog then adds --mcp:
willow init --base-url https://your-org.withwillow.ai/mcp --mcp <server>
After that, ask your AI agent in plain language and it calls your tools through Willow. You can also call them yourself:
willow doctor # check the environment
willow tools list -d # browse the tool catalog
willow tools call <tool> '<json>'
Commands
| Command | Subcommands |
|---|---|
willow auth | login, logout, whoami, status, token |
willow context | list, use, add, remove |
willow tools | list, info, grep, call, servers, refresh |
willow resources | list, grep, read |
willow daemon | status, refresh, stop, enable, disable |
willow config | get, set, show, edit |
willow doctor | Diagnose the environment, auth, daemon, and MCP reachability |
willow init | Create ~/.config/willow/config.json and install the skill |
willow update | Update the CLI, then reinstall the skill |
willow install-skill | Install or refresh the Willow skill for every detected AI agent |
willow uninstall-skill | Remove the Willow skill from every detected AI agent |
Add --help at any level for details, for example willow tools call --help.
willow auth
willow auth login # sign in with OAuth (opens your browser)
willow auth logout # remove stored OAuth tokens
willow auth whoami # identity, org, and current context
willow auth status # offline check: exits 0 if signed in, 4 if you need to log in
willow auth token # print the current bearer token to stdout
willow auth status is a cheap preflight check for scripts and agent sessions:
willow auth status && willow tools call my_tool '{}'
You don't need to sign in again each time the access token expires. When it is close to expiring, the CLI refreshes it with the stored refresh token and saves the new one. willow auth status still exits 0 while the access token is expired but a refresh token is stored. It exits 4 when there is no refresh token, or when the session end time the server reported has passed, and you then need willow auth login.
willow auth token prints only the token, so you can pipe it:
curl -H "Authorization: Bearer $(willow auth token)" https://example.com/api
willow context
A context is a named target (an MCP server, a toolkit, or both) in your org. Every command that talks to a server uses the active context.
willow context list # active context is starred
willow context add slack-eng --mcp slack --toolkit engineering
willow context add github-platform --mcp github --toolkit platform --use
willow context use slack-eng
willow context remove old-context
To use a different context for one command without switching, pass the global --context <name> flag.
willow tools
willow tools list # tool names
willow tools list -d # names and descriptions
willow tools info <tool> # input schema for one tool
willow tools grep <pattern> # search tool names
willow tools grep <pattern> -d # also search descriptions
willow tools servers # list the integrations on your gateway
willow tools servers -d # include descriptions
willow tools call <tool> '<json>' # call with inline JSON
echo '<json>' | willow tools call <tool> # call with JSON from stdin
willow tools call <tool> --force-auth '<json>' # sign in first if needed
willow tools refresh # clear the cached tool catalog
willow tools call writes the text content of the response to stdout. If the response has no text, it prints the JSON instead.
When you don't know which tool to look for, start with willow tools servers, then use a server's slug as the pattern for willow tools grep.
willow resources
Some MCP servers expose resources: content you read by URI (files, records, documents) rather than actions you call. Many servers have none.
willow resources list # resources and resource templates
willow resources list -d # include descriptions
willow resources grep <pattern> # search URIs and names
willow resources read '<uri>' # print the content to stdout
A resource template is a URI with placeholders, such as github://repos/{owner}/{repo}/{path}. Fill in the placeholders yourself, then pass the URI to read.
willow daemon
The CLI keeps MCP connections warm in a background daemon and caches the tool list for settings.cacheTtl seconds. Switching context (willow context use) or signing in again (willow auth login) restarts it automatically.
willow daemon refresh # drop the cache now; the next command fetches a fresh catalog
The other subcommands are status, stop, enable, and disable.
willow config
willow config show # whole config as JSON
willow config get <key> # one value (dot notation)
willow config set <key> <value> # set a value
willow config edit # open in $VISUAL or $EDITOR; validated on save
For example:
willow config set settings.timeout 30
willow config set settings.daemon false
willow doctor
Checks the Node.js version, the config file, your contexts, sign-in state, the daemon, MCP server reachability, and whether the skill is installed for each detected agent. It exits non-zero if any check fails, so you can run it in CI.
willow update
willow update # install the latest @willowai/cli globally
willow update --check # only report whether an update is available
willow update also reinstalls the skill that ships with the new version. --check changes nothing.
willow install-skill and willow uninstall-skill
willow install-skill writes the skill to ~/.agents/skills/willow/SKILL.md and links it into each detected agent's skills directory. willow init and willow update run it for you.
willow uninstall-skill removes the skill from every agent. It doesn't uninstall the CLI, change your config, or revoke tokens. Run willow init again to reinstall it.
Global options
| Option | Description |
|---|---|
-c, --config <path> | Use a different config file |
--context <name> | Use a specific context for this command only |
-d, --with-descriptions | Include descriptions in list and grep output |
-h, --help | Show help |
-v, --version | Show the version |
Configuration
The config file is ~/.config/willow/config.json. Override it with -c or WILLOW_CONFIG_PATH.
{
"enabled": true,
"baseUrl": "https://acme.withwillow.ai/mcp",
"currentContext": "default",
"contexts": {
"default": { "mcp": null, "toolkit": null },
"slack-eng": { "mcp": "slack", "toolkit": "engineering" }
},
"settings": {
"timeout": 60,
"daemon": true
}
}
You can reference environment variables anywhere in the file, for example "token": "${MY_TOKEN}".
Top-level fields
| Field | Description |
|---|---|
enabled | Set to false to stop all commands from running |
org | Your organization slug for the CLI's default gateway lookup. Set baseUrl to use the exact URL from Connect MCP. |
baseUrl | The full MCP URL from Connect MCP, including /mcp. Takes precedence over org. |
userAccessKey | A user access key. Switches the CLI to STDIO mode through npx @mcp-s/mcp |
token | A static bearer token, for CI. OAuth through willow auth login is the default |
headers | Extra HTTP headers sent on every gateway request, such as x-user-email. See Act as a user from your own agent |
currentContext | The active context |
contexts | Named contexts: { mcp, toolkit, allowedTools, disabledTools } |
settings | Behavior settings (below) |
Context fields
| Field | Description |
|---|---|
mcp | MCP server identifier |
toolkit | Toolkit name |
allowedTools | Glob patterns of tool names to allow |
disabledTools | Glob patterns of tool names to hide |
settings
| Field | Default | Description |
|---|---|---|
timeout | 1800 | Request timeout in seconds |
maxRetries | 3 | Retries for transient errors (0 to disable) |
retryDelay | 1000 | Base retry delay in milliseconds |
daemon | true | Keep connections warm in the background daemon |
daemonTimeout | 300 | Daemon idle timeout in seconds |
cacheTtl | 300 | Tool list cache TTL in seconds (0 to disable) |
history | false | Append each command to history.jsonl |
Act as a user from your own agent
An agent you run yourself, such as a Slack bot, can call tools as the person it is serving. Set token to an API token with only the run:impersonate scope, and name the user with an x-user-email (or x-user-id) header:
{
"baseUrl": "https://acme.withwillow.ai/mcp",
"token": "${WILLOW_API_TOKEN}",
"headers": { "x-user-email": "${WILLOW_USER_EMAIL}" }
}
Then set the email for each command:
WILLOW_USER_EMAIL=dana@example.com willow tools call <tool> '<json-args>'
Each call runs with that user's allowed tools and connected accounts, and the audit log attributes it to them. Commands that name a user always connect directly instead of through the daemon, so calls for different users never share a connection. If WILLOW_USER_EMAIL is unset, the command fails before sending anything. willow tools servers doesn't support acting as a user, so use willow tools grep or willow tools list to discover tools.
Set the email from your agent's code, never from anything the model can control: whoever chooses that value chooses who the call runs as. See Authenticate a Slack Agent for the full setup and its security checklist.
Environment variables
| Variable | Description |
|---|---|
WILLOW_CONFIG_PATH | Use a different config file |
WILLOW_DEBUG | Print debug output to stderr |
WILLOW_STRICT_ENV | Set to false to warn instead of failing on a missing ${VAR} |
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Client error (bad arguments, missing config) |
2 | Server error (the tool call failed) |
3 | Network error |
4 | Not signed in. Run willow auth login |
Results go to stdout. Errors, diagnostics, and progress messages go to stderr.
Running inside OpenAI Codex
When an AI agent runs willow from inside the OpenAI Codex CLI, commands can fail with network errors (ECONNREFUSED, ETIMEDOUT) or a sign-in timeout. Codex's default workspace-write sandbox blocks outbound network access, so the CLI can't reach the Willow gateway.
The simplest setup is to sign in once from a normal terminal, outside Codex:
willow auth login
Then allow network access in the Codex sandbox. Add this to ~/.codex/config.toml:
[sandbox_workspace_write]
network_access = true
That covers tool calls once you're signed in, because reading the cached token in ~/.config/willow/ is allowed.
Signing in or refreshing the token writes to ~/.config/willow/, which is outside the sandbox's writable roots. To sign in from inside Codex, also add that directory:
[sandbox_workspace_write]
network_access = true
writable_roots = ["~/.config/willow"]
As a last resort, you can turn off the sandbox entirely (filesystem and network):
codex --sandbox danger-full-access