CLI
mcp-s-cli is a command-line tool for connecting AI clients to Willow without a desktop app. Use it from a terminal, in CI/CD pipelines, or anywhere you prefer the command line over a GUI.
This reference covers @mcp-s/cli version 0.0.25.
Install
npm install -g @mcp-s/cli
Quick setup
Open the MCP-S CLI tab in the Connect MCP modal to get your org name and MCP server identifier, then run:
mcp-s-cli init --org <your-org> --mcp <server-name>
The CLI opens your browser to complete authentication. Afterwards, run mcp-s-cli to list available tools.
Commands
mcp-s-cli (no arguments)
Lists all tools available on the configured server.
mcp-s-cli
mcp-s-cli -d # include descriptions
mcp-s-cli init
Configures the CLI. Writes to ~/.config/mcp-s-cli/config.json. Triggers browser-based login automatically.
mcp-s-cli init --org <org>
mcp-s-cli init --base-url <url>
mcp-s-cli init --org <org> --mcp <server-id>
| Flag | Description |
|---|---|
--org <org> | Your Willow org name. Resolves to https://<org>.mcp-s.com/mcp |
--base-url <url> | Custom server URL (mutually exclusive with --org) |
--mcp <id> | MCP server identifier to connect to |
--toolkit <name> | Toolkit name |
--token <token> | Static bearer token (skips OAuth) |
Run mcp-s-cli init with no flags for an interactive setup wizard.
mcp-s-cli login
Authenticates with your Willow org. Opens a browser window.
mcp-s-cli login
mcp-s-cli login --remote # token-based auth, no local callback server
mcp-s-cli logout
Removes stored OAuth tokens.
mcp-s-cli logout
mcp-s-cli check-auth
Checks authentication state without making a network request. Exits 0 if authenticated, 4 if login is needed. Useful as a preflight check in scripts.
mcp-s-cli check-auth
mcp-s-cli grep <pattern>
Searches tool names by substring (case-insensitive, hyphen and underscore treated as equivalent).
mcp-s-cli grep file
mcp-s-cli grep read -d # include descriptions
mcp-s-cli info <tool>
Shows the input schema for a tool.
mcp-s-cli info read_file
mcp-s-cli call <tool> [args]
Calls a tool with JSON arguments.
mcp-s-cli call read_file '{"path": "./src/index.ts"}'
cat input.json | mcp-s-cli call read_file # read args from stdin
mcp-s-cli call read_file - # explicitly read from stdin
| Flag | Description |
|---|---|
--force-auth | Trigger login if token is missing or expired before calling |
--org, --base-url, --mcp, --toolkit, --token | Override config for this invocation only |
mcp-s-cli get-servers
Lists MCP servers available on the configured gateway.
mcp-s-cli get-servers
mcp-s-cli whoami
Shows the active config path, authentication state, history file, and installed skill locations.
mcp-s-cli whoami
mcp-s-cli config
Reads and writes individual settings in config.json.
mcp-s-cli config set settings.timeout 60
mcp-s-cli config get settings.timeout
mcp-s-cli config show
mcp-s-cli config --help # list all keys with types and defaults
mcp-s-cli kill-daemon
Stops the background daemon process used internally for connection caching.
mcp-s-cli kill-daemon
Utility commands
| Command | Description |
|---|---|
mcp-s-cli clear | Reset config.json to {} |
mcp-s-cli clear-auth | Clear stored OAuth tokens |
mcp-s-cli clear-history | Delete ~/.config/mcp-s-cli/history.jsonl |
mcp-s-cli enable | Re-enable the CLI after disabling |
mcp-s-cli disable | Disable the CLI without removing config |
Global options
These options work with most commands.
| Option | Description |
|---|---|
-h, --help | Show help |
-v, --version | Show version |
-d, --with-descriptions | Include tool descriptions in list/grep output |
-c, --config <path> | Path to a config file (overrides default) |
--org <org> | Org name override for this invocation |
--base-url <url> | Server URL override for this invocation |
--mcp <id> | MCP server identifier override |
--toolkit <name> | Toolkit name override |
--token <token> | Static bearer token override |
--force-auth | Trigger login if token is missing or expired |
--remote | Use token-based remote auth (with login) |
Configuration
Config file: ~/.config/mcp-s-cli/config.json
Auth tokens: ~/.config/mcp-s-cli/auth.json
Connection fields
| Key | Type | Description |
|---|---|---|
org | string | Org name. Derives URL as https://<org>.mcp-s.com/mcp |
baseUrl | string | Custom server URL (alternative to org) |
mcp | string | MCP server identifier |
toolkit | string | Toolkit name |
token | string | Static bearer token |
Tool filtering
| Key | Type | Description |
|---|---|---|
allowedTools | string[] | Glob patterns. Only matching tools are visible |
disabledTools | string[] | Glob patterns. Matching tools are hidden (takes precedence over allowedTools) |
Behavior (settings.*)
| Key | Type | Default | Description |
|---|---|---|---|
settings.timeout | number | 1800 | Request timeout in seconds |
settings.maxRetries | number | 3 | Max retry attempts (0 to disable) |
settings.retryDelay | number | 1000 | Base retry delay in milliseconds |
settings.daemon | boolean | true | Enable background connection caching |
settings.daemonTimeout | number | 300 | Daemon idle timeout in seconds |
settings.cacheTtl | number | 300 | Tool list cache TTL in seconds (0 to disable) |
settings.history | boolean | false | Append invocations to history.jsonl |
Environment variables
| Variable | Description |
|---|---|
MCP_S_CLI_DEBUG=1 | Enable debug output to stderr |
MCP_S_CLI_CONFIG_PATH | Override config file path |
MCP_S_CLI_STRICT_ENV=false | Warn instead of error on missing ${VAR} references in config |