clihub

clihub is a tool that converts a Model Context Protocol (MCP) server into a standalone, compiled CLI binary.

It automates the following workflow:

1. Connects to and initializes an MCP endpoint (via HTTP or stdio).
2. Discovers available tools from the server.
3. Generates Go code where each MCP tool is represented as a unique CLI subcommand.
4. Compiles the code into a single, static binary.

The resulting binary is completely independent; it can be distributed and run in environments without requiring clihub or any specific runtime dependencies.

clihub operates with two distinct authentication surfaces depending on whether you are using the core tool or a generated binary:

1. clihub generate authentication: Used by the clihub tool itself to authenticate with a target MCP server to discover available tools.
2. Generated CLI runtime authentication: Authentication logic embedded directly into the binaries produced by clihub generate. This allows the resulting CLI to authenticate tool calls at runtime.

Both surfaces support similar authentication types, but they are implemented in different parts of the codebase.

clihub operates as a build-time transformer that converts Model Context Protocol (MCP) servers into standalone CLI tools. The process follows these high-level steps:

1. Discovery: Connects to an MCP server (via HTTP or stdio) and performs an initialization handshake.
2. Schema Extraction: Calls tools/list to collect tool schemas and filters them based on user-provided include/exclude rules.
3. Codegen: Converts MCP tool schemas into Go/Cobra flag definitions and renders a temporary Go project using templates.
4. Compilation: Invokes the Go toolchain to compile the generated source into a static binary (with CGO_ENABLED=0) for the target platform(s).
5. Verification: Runs a smoke test (typically --help) on the host-platform binary to ensure it is functional.

The core orchestration is handled by the clihub generate command.

clihub generate [flags]

When you generate a CLI using clihub, the resulting binary includes built-in authentication capabilities:

• Persistent Flags: Supports flags like --auth-token and --auth-type directly.
• Hidden Auth Flags: Includes the same advanced auth flags used by clihub, accessible via --help-auth.
• Auth Command: Includes an auth command in HTTP mode to facilitate token-based workflows.

When running clihub generate against an HTTP endpoint, the tool resolves the authentication provider using the following precedence order:

1. Explicit flags: Using --auth-type and its associated flags.
2. Token flag: Using --auth-token (which infers a bearer token provider).
3. Environment variable: The CLIHUB_AUTH_TOKEN environment variable.
4. Stored credentials: An entry in ~/.clihub/credentials.json that matches the server URL.
5. No-auth: Defaults to a no-auth provider if no other method is found.

clihub is designed to bridge the gap between MCP servers and standard CLI workflows. Use it when you need to:

• Automate MCP tool usage within shell scripts or CI/CD pipelines.
• Use MCP tools in shell-first or SSH-based workflows.
• Run tools in environments where an AI agent is not actively running.
• Distribute a single executable tool that has no runtime dependency on the clihub generator.

If no explicit authentication is configured for an HTTP server, clihub attempts to auto-detect requirements:

1. It probes the MCP URL via an HTTP POST request.
2. If the server responds with a 401 status, clihub parses the WWW-Authenticate challenge.
3. If the bearer challenge contains OAuth metadata, clihub triggers the OAuth flow.
4. If discovery fails, clihub returns a guidance error suggesting the user provide a token or use the --oauth flag.

Understanding how an MCP tool becomes a CLI command is essential for debugging generation or command flow issues. The transformation follows this mapping:

• MCP Tool: The raw tool definition from the MCP server.
• Internal ToolDef: The normalized internal representation used by clihub.
• Generated Cobra Command: The final CLI command structure.

Schema Mapping:

• Schema Properties: The JSON Schema properties of an MCP tool are mapped to ToolOption objects.
• Flags: These ToolOption objects are then rendered as typed flags in the generated CLI, supporting optional enum and default behaviors.

clihub stores credentials in a JSON file at: ~/.clihub/credentials.json

Storage Details:

• Schema: Version 2 stores credentials keyed by server URL, including the provider type and provider-specific fields.
• Migration: Version 1 records are automatically migrated to version 2 upon loading.
• Permissions: The credentials file is saved with 0600 mode, and the parent directory is created with 0700 mode.

Known Limitations:

• Writes are not currently atomic.
• File locking is not implemented.
• Secrets are stored in a file rather than a system keychain.

Before performing release actions or pushing to main, ensure the repository hooks are installed. This sets up the pre-push checks and configures your local git to use --follow-tags by default.

Run the following command:

bash scripts/install-hooks.sh

Generated CLIs handle authentication at runtime via an auth subcommand.

Common Auth Commands

• OAuth browser flow: ./out/linear auth (automatically discovers endpoints via RFC 9728 / RFC 8414)
• Manual bearer token: ./out/linear auth --token $TOKEN
• Check status: ./out/linear auth status
• Logout: ./out/linear auth logout

Authentication Precedence

When resolving credentials, clihub follows this order:

1. --auth-token flag
2. --auth-type + related flags (e.g., --auth-header-name, --auth-key-file)
3. CLIHUB_AUTH_TOKEN environment variable
4. ~/.clihub/credentials.json (persisted from previous sessions)
5. Unauthenticated

Authentication flags are often hidden from the default help output in clihub generate. To see all available authentication options, use the --help-auth flag.

Commonly used flags include:

• --oauth: Alias for --auth-type oauth2.
• --auth-token: Provides a bearer token.
• --auth-type: Specifies the provider (e.g., api_key, basic).
• --auth-header-name: Customizes the header name for auth.
• --auth-key-file: Path to a key file.
• --client-id / --client-secret: Credentials for OAuth flows.
• --save-credentials: Instructs clihub to persist the credentials to ~/.clihub/credentials.json.