Knotbind CLI

All commands from your terminal.

The Knotbind CLI is a single executable with no extra dependencies. It covers everything from local OpenAPI-to-MCP generation to scheduled Checks, fix proposals and Owner approvals. Install it once and use it in scripts, CI, or locally.

Install

The CLI ships in this repository. Install it globally:

npm install -g knotbind

Or run it directly without installing:

npx knotbind --help

Or from a local checkout:

node bin/knotbind.mjs --help

Configuration

All commands read two environment variables:

Variable	Default	Required for
KNOTBIND_URL	https://www.knotbind.com	All commands (points the CLI at your region)
KNOTBIND_API_KEY	—	Everything except readiness, signup, openapi-to-mcp, modules list

Get your API key from the Dashboard or by running{" "} knotbind signup.

Public commands

These run without an API key. They do not authenticate to your workspace.

readiness

Runs a read-only Agent Readiness Check against any website or MCP server. Outputs a score out of 100 with a fix list.

knotbind readiness https://api.your-business.example.com

Options

Flag	Description
--depth	Maximum number of OpenAPI operations to inspect (default 20).
--format	Output format: json or text (default text).

signup

Creates a new workspace and prints the first API key. The email and company name must not already exist.

knotbind signup --company Acme --name "Jane Doe" --email jane@acme.example

openapi-to-mcp

Generates an MCP server from an OpenAPI description. Reads a local JSON file or fetches from a URL.

knotbind openapi-to-mcp ./openapi.json --ops list_users,get_user --max 100

Options

Flag	Description
--max <n>	Limit to the first n operations (default 50, max 100).
--ops op1,op2,...	Select specific operations by their operationId.
--format package	Output a distributable server package.
--out <file>	Write the package to this path (default: stdout for JSON, ./server.tar.gz for package).
--allow-write	Generate mutating tools. Requires Owner approval before Checks can run.
--auth bearer\|apiKey\|basic	Auth scheme to declare on the generated MCP server.
--auth-header X-My-Header	Custom header name for API key auth.

Package format

With --format package, the CLI produces a server.tar.gz containing an executable MCP server. Run it directly or deploy a private endpoint.

knotbind openapi-to-mcp ./openapi.json --format package --out server.tar.gz --allow-write
node server.tar.gz --mcp

Connected commands

These commands require KNOTBIND_API_KEY. They act on your workspace.

connect

Registers an MCP server for monitoring. The URL must be public HTTPS.

knotbind connect https://mcp.your-business.example/mcp

status

Prints health, open Findings, scheduled Checks and the last Run result.

knotbind status

run

Runs all scheduled Checks now. Use this for an on-demand verification.

knotbind run

tools

Lists live tools from the MCP server you registered.

knotbind tools

tool-call

Calls one MCP tool once. Not scheduled. Write tools require --allow-write and Owner approval.

knotbind tool-call get_customer --args '{"id": "123"}'

finding

Opens a Finding, its diagnosis, and the Repair Proposal.

knotbind finding

runs

Shows recent Check Runs.

knotbind runs --limit 10

add-check

Adds a Check for a tool. Write-capable tools require --allow-write.

knotbind add-check get_user --allow-write

remove-check

Removes a previously added Check by ID.

knotbind remove-check chk_123abc

assistants

Shows which AI Assistants (ChatGPT, Claude, Grok, Meta Muse, and many more) are currently connected through your relay.

knotbind assistants

relay

Creates a relay URL that records the connecting assistant's identity. Shown only once, then expires.

knotbind relay

mcp-config

Prints a ready-to-paste MCP client configuration for connecting an AI Assistant to your Knotbind MCP server.

knotbind mcp-config

request-plan

Sends an Owner-approved plan change request (Pro or Business).

knotbind request-plan business --reason "Need EU hosting"

keys

Lists API keys, creates a new key, or revokes an existing one.

knotbind keys
knotbind keys create --scopes read,write
knotbind keys revoke key_abc123

Gateway modules

Manage Gateway modules from the CLI.

knotbind modules
knotbind modules enable-all
knotbind modules disable semantic_cache

Examples

CI: fail the build on a breaking API change

KNOTBIND_API_KEY=kb_live_... knotbind run
"hl-c"># Exit non-zero if any Check failed

Local: generate and test an MCP server

knotbind openapi-to-mcp ./api.json --ops list,get --format package --out server.tar.gz
node server.tar.gz --mcp &;
knotbind readiness http://localhost:3000/mcp --depth 10

Error handling

The CLI prints JSON to stdout and human-readable text to stderr. On failure, the exit code is non-zero and the error message includes the HTTP status and a knot_error field:

{}

{"error":"KNOTBIND_API_KEY is required for this command","knot_error":"unauthorized"}