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.31.

Install

npm install -g @mcp-s/cli

Quick setup

Select Willow CLI in the Connect MCP dialog 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.

Running inside OpenAI Codex

When an AI agent runs mcp-s-cli from inside the OpenAI Codex CLI, commands can fail with connection or network errors (ECONNREFUSED, ETIMEDOUT, or an OAuth/login timeout). This is not a mcp-s-cli bug: Codex's default workspace-write sandbox blocks outbound network access, so the CLI can't reach the Willow gateway.

Give Codex network access with one of the options below.

Recommended: allow network in the workspace sandbox

Keep the filesystem sandbox but permit outbound network. Add this to ~/.codex/config.toml (or $CODEX_HOME/config.toml):

[sandbox_workspace_write]
network_access = true

Or enable it for a single session without editing config:

codex --sandbox workspace-write -c 'sandbox_workspace_write.network_access=true'

This is enough for tool calls once you're already logged in — reading the cached token from ~/.config/mcp-s-cli/ is allowed (reads work everywhere in workspace-write).

Logging in from inside Codex

mcp-s-cli login and token refresh write the token to ~/.config/mcp-s-cli/, which is outside the sandbox's writable roots (only the workspace and /tmp are writable). So enabling network alone isn't enough to authenticate from inside Codex.

The simplest approach is to log in once from a normal terminal (outside Codex); after that, network_access = true covers everything the agent does. If you must log in or refresh tokens from inside Codex, also add the config directory as a writable root:

[sandbox_workspace_write]
network_access = true
writable_roots = ["~/.config/mcp-s-cli"]

Alternative: full access

Disables the Codex sandbox entirely (filesystem and network). This is the quickest fix, but it's the least restrictive — prefer the option above when you can:

codex --sandbox danger-full-access

note

mcp-s-cli also runs a background daemon that listens on a Unix socket under /tmp/mcp-s-cli-<uid>. The workspace-write sandbox already permits writes to the system temp directory, so the daemon works once network access is enabled. If you still hit issues, disable it with mcp-s-cli config set settings.daemon false.

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. Exits 0 if authenticated, 4 if login is needed. Useful as a preflight check in scripts.

By default the check is offline (no network request) — it only verifies that a non-expired token is present on disk. Pass --online to also validate the token against the server, which catches tokens that are present but rejected server-side (e.g. expired or revoked). If the server is unreachable, --online prints a warning and falls back to the offline result.

mcp-s-cli check-auth             # offline check (fast preflight)
mcp-s-cli check-auth --online    # also validate the token against the server

`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

`mcp-s-cli update`

Self-updates to the latest published @mcp-s/cli. It queries the npm registry for the latest version, compares it to the one you're running, and — unless --check — applies the update.

Because the CLI is most often launched via npx @mcp-s/cli (which caches the package and can keep running a stale version), update adapts to how it was invoked:

Launched via npx — there's no global install to upgrade, so it removes only the cached @mcp-s/cli npx entries. Other npx-cached tools are left untouched. The next npx @mcp-s/cli then resolves the latest version.
Global install — runs npm install -g @mcp-s/cli@latest, then also drops any cached @mcp-s/cli npx entries so npx-based agents don't keep the old build.

mcp-s-cli update             # upgrade to the latest version
mcp-s-cli update --check     # report whether a newer version exists, without changing anything

Flag	Description
`--check`	Only report whether an update is available; makes no changes

tip

If a wrapper or agent runs the CLI via npx and still reports an old version, run it once as npx @mcp-s/cli@latest ... to bypass the cache entirely.

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`)
`--online`	Validate the token against the server (with `check-auth`)
`--check`	Report whether an update is available without applying it (with `update`)

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

CLI

Install

Quick setup

Running inside OpenAI Codex

Recommended: allow network in the workspace sandbox

Logging in from inside Codex

Alternative: full access

Commands

`mcp-s-cli` (no arguments)

`mcp-s-cli init`

`mcp-s-cli logout`

`mcp-s-cli check-auth`

`mcp-s-cli grep <pattern>`

`mcp-s-cli info <tool>`

`mcp-s-cli call <tool> [args]`

`mcp-s-cli get-servers`

`mcp-s-cli whoami`

`mcp-s-cli config`

`mcp-s-cli kill-daemon`

`mcp-s-cli update`

Utility commands

Global options

Configuration

Connection fields

Tool filtering

Behavior (`settings.*`)

Environment variables

On this page

Was this helpful?

Install​

Quick setup​

Running inside OpenAI Codex​

Recommended: allow network in the workspace sandbox​

Logging in from inside Codex​

Alternative: full access​

Commands​

mcp-s-cli (no arguments)​

mcp-s-cli init​

mcp-s-cli login​

mcp-s-cli logout​

mcp-s-cli check-auth​

mcp-s-cli grep <pattern>​

mcp-s-cli info <tool>​

mcp-s-cli call <tool> [args]​

mcp-s-cli get-servers​

mcp-s-cli whoami​

mcp-s-cli config​

mcp-s-cli kill-daemon​

mcp-s-cli update​

Utility commands​

Global options​

Configuration​

Connection fields​

Tool filtering​

Behavior (settings.*)​

Environment variables​

On this page

Was this helpful?

Install

Quick setup

Running inside OpenAI Codex

Recommended: allow network in the workspace sandbox

Logging in from inside Codex

Alternative: full access

Commands

`mcp-s-cli` (no arguments)

`mcp-s-cli init`

`mcp-s-cli login`

`mcp-s-cli logout`

`mcp-s-cli check-auth`

`mcp-s-cli grep <pattern>`

`mcp-s-cli info <tool>`

`mcp-s-cli call <tool> [args]`

`mcp-s-cli get-servers`

`mcp-s-cli whoami`

`mcp-s-cli config`

`mcp-s-cli kill-daemon`

`mcp-s-cli update`

Utility commands

Global options

Configuration

Connection fields

Tool filtering

Behavior (`settings.*`)

Environment variables