Skip to main content

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.

note

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​

CommandSubcommands
willow authlogin, logout, whoami, status, token
willow contextlist, use, add, remove
willow toolslist, info, grep, call, servers, refresh
willow resourceslist, grep, read
willow daemonstatus, refresh, stop, enable, disable
willow configget, set, show, edit
willow doctorDiagnose the environment, auth, daemon, and MCP reachability
willow initCreate ~/.config/willow/config.json and install the skill
willow updateUpdate the CLI, then reinstall the skill
willow install-skillInstall or refresh the Willow skill for every detected AI agent
willow uninstall-skillRemove 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​

OptionDescription
-c, --config <path>Use a different config file
--context <name>Use a specific context for this command only
-d, --with-descriptionsInclude descriptions in list and grep output
-h, --helpShow help
-v, --versionShow 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​

FieldDescription
enabledSet to false to stop all commands from running
orgYour organization slug for the CLI's default gateway lookup. Set baseUrl to use the exact URL from Connect MCP.
baseUrlThe full MCP URL from Connect MCP, including /mcp. Takes precedence over org.
userAccessKeyA user access key. Switches the CLI to STDIO mode through npx @mcp-s/mcp
tokenA static bearer token, for CI. OAuth through willow auth login is the default
headersExtra HTTP headers sent on every gateway request, such as x-user-email. See Act as a user from your own agent
currentContextThe active context
contextsNamed contexts: { mcp, toolkit, allowedTools, disabledTools }
settingsBehavior settings (below)

Context fields​

FieldDescription
mcpMCP server identifier
toolkitToolkit name
allowedToolsGlob patterns of tool names to allow
disabledToolsGlob patterns of tool names to hide

settings​

FieldDefaultDescription
timeout1800Request timeout in seconds
maxRetries3Retries for transient errors (0 to disable)
retryDelay1000Base retry delay in milliseconds
daemontrueKeep connections warm in the background daemon
daemonTimeout300Daemon idle timeout in seconds
cacheTtl300Tool list cache TTL in seconds (0 to disable)
historyfalseAppend 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​

VariableDescription
WILLOW_CONFIG_PATHUse a different config file
WILLOW_DEBUGPrint debug output to stderr
WILLOW_STRICT_ENVSet to false to warn instead of failing on a missing ${VAR}

Exit codes​

CodeMeaning
0Success
1Client error (bad arguments, missing config)
2Server error (the tool call failed)
3Network error
4Not 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