bridgectl

bridgectl is the developer CLI for the ERPBridge ecosystem. It manages environments, registers and tests ERP APIs, generates and validates MCP tool schemas, and monitors the middleware through real-time log streaming and cache analytics.

The CLI uses the ERPBridge middleware through a REST API. It supports Table, JSON, and YAML output.

The CLI also bundles the bridgectl-ops Agent Skill. Install it locally with bridgectl skill install; use --project for a project-scoped install or --dir to select an explicit destination.

Quick start

Build the CLI

make build

Verify the server connection

./bridgectl tool get

Command groups

Group	Description	Key commands
bridgectl api	Manage ERP API endpoints	api register, api list, api test
bridgectl tool	Manage MCP tool resources (V2 Control Plane)	tool apply, tool generate, tool get, tool delete
bridgectl cache	Manage tool cache	cache stats, cache flush
bridgectl log	Manage and view logs	log tail, log stats
bridgectl context	Manage bridgectl contexts	context list, context set
bridgectl token	Manage ERPBridge API tokens	token create, token list, token revoke
bridgectl completion	Generate shell autocompletion	bash, zsh, fish, powershell
bridgectl doc	Generate Markdown documentation for bridgectl	—
bridgectl skill	Manage the bundled Agent Skill	skill install
bridgectl version	Print the version number of bridgectl	—

Global options

  -c, --context string   Override active context
  -h, --help             help for bridgectl
  -o, --output string    Output format: table, json, yaml (default "table")
      --token string     API token for the ERPBridge server
  -v, --verbose          Show full HTTP request/response detail

Typical workflow

1. Choose and verify a configured context with bridgectl context list -o json.
2. Register your ERP API in that context — bridgectl api register --context <name> --name erp --url <url> --credential-ref ERP_API_KEY ...
3. Test the API through the server — bridgectl api test --context <name> erp; use --local only for an explicit legacy diagnostic.
4. Generate a draft to a temporary stream, review it, and keep the applied source under manifests/<module>/.
5. Apply the reviewed manifest — bridgectl tool apply --context <name> -f manifests/<module>/tools.yaml.
6. Verify — bridgectl tool get --context <name>

New to ERPBridge?

Follow the step-by-step onboarding guide — it walks through this exact workflow against mock-erp.

Exit codes

The CLI exits with a stable numeric code so scripts and AI agents can react programmatically.

Code	Name	Trigger scenario
0	SUCCESS	Command succeeded
1	GENERAL_ERROR	Server 500 or an unhandled error
2	BAD_ARGS	Malformed URL, missing http:// protocol, invalid arguments
3	NOT_FOUND	A requested API or resource is not in the selected registry
4	AUTH_FAIL	Authentication failure
5	CONFLICT	Resource conflict
6	TIMEOUT	Request timed out
7	PRECONDITION_FAIL	MISCONFIGURED_CONTEXT (URL not set), NO_CONTEXT, or another required precondition

Agent-friendly errors

When -o json is used, errors are written to stdout as a structured JSON payload so agent subprocesses can parse them:

bridgectl -o json — error output

{
  "error": "RESOURCE_NOT_FOUND",
  "message": "The requested resource was not found",
  "suggestion": "Check the selected context and list the available resources.",
  "code": 3
}

note

Check code (the numeric exit code) and error (the machine-readable code) together. The exit code also propagates to the process exit status, so $? works in plain shell scripts too. Control-plane errors never include upstream bodies, credentials, or internal stack details.

The configured mcp-server is a control-plane host root. Only an exact /mcp or /mcp/ suffix is normalized away; other paths return CONTROL_PLANE_URL_INVALID. A legacy global API registry is not ignored: scrub and explicitly migrate it to one selected context before writing.

Reference

Every command has a dedicated reference page. See the command reference sidebar for the full list, grouped by parent command.