AI Hub CLI — Installation & documentation

Features

🔌 AI Hub connection Configure once (AI_HUB_URL, AI_HUB_API_KEY), then use connect, tools, call, and file commands.

📄 Workspace files List, inspect metadata, and download files from AI Hub workspaces.

🗂️ FUSE mount Mount workspaces as filesystems with lazy loading (Linux, macOS with macFUSE, Windows with WinFsp).

🐍 Python executor MCP server: execute_python with persistent state and optional UV venvs.

💻 Terminal executor MCP server: execute_terminal with foreground and background processes.

🔀 Combined executor Single MCP server exposing both Python and terminal tools (default in the Docker image).

🤖 ACP connector MCP bridge to local ACP agents over stdio (agent profiles via JSON config).

🗄️ Database connectors PostgreSQL, MySQL, MS SQL Server, ClickHouse, Oracle, SQLite — each exposes execute_sql.

🌐 REST connector OpenAPI 3.0 specs become MCP tools calling your HTTP APIs.

📂 Filesystem connector Folder as MCP resources (filesystem://) with configurable read/write tools.

🔗 MCP with AI Hub Register stdio MCP servers or connect to remote streamable-HTTP MCP URLs.

🖥️ Cross-platform Linux, macOS, and Windows binaries; optional self-update on a schedule.

Quick install

Run one of the following to install the latest ai-hub-cli for your OS and architecture. Use the Linux / macOS or Windows toggle at the top of the page to switch examples sitewide.

curl -fsSL https://ai-hub-cli.s3.de.io.cloud.ovh.net/install.sh | sh

Note: Detects OS and CPU architecture, downloads the matching binary, and installs it on your PATH.

# PowerShell (recommended) – one command, no admin:
irm https://ai-hub-cli.s3.de.io.cloud.ovh.net/install.ps1 | iex

REM From classic Cmd, invoke the same installer via PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://ai-hub-cli.s3.de.io.cloud.ovh.net/install.ps1 | iex"

The install script is designed for PowerShell; Cmd users can run the line above or open PowerShell and use the shorter irm … | iex command.

Note: Installs to %LOCALAPPDATA%\ai-hub-cli and adds it to your user PATH. No administrator rights required.

Alternative (Git Bash / WSL):

curl -fsSL https://ai-hub-cli.s3.de.io.cloud.ovh.net/install.sh | sh

Manual download

Download a binary directly (same artifacts the install scripts use):

Linux (amd64) ai-hub-cli-linux-amd64 macOS (Intel) ai-hub-cli-darwin-amd64 macOS (Apple Silicon) ai-hub-cli-darwin-arm64 Windows (amd64) ai-hub-cli-windows-amd64.exe

Versioned releases: GitHub Releases.

Configuration

Most commands that talk to AI Hub need a base URL and API key. You can use a .env file in the working directory (loaded automatically) or export variables in your shell.

Environment variables

export AI_HUB_URL="https://your-ai-hub.example.com"
export AI_HUB_API_KEY="your-api-key-here"

$env:AI_HUB_URL = "https://your-ai-hub.example.com"
$env:AI_HUB_API_KEY = "your-api-key-here"

set AI_HUB_URL=https://your-ai-hub.example.com
set AI_HUB_API_KEY=your-api-key-here

For a persistent user environment, use setx or Windows Settings → Environment variables.

Command-line flags

Flags override environment variables for that invocation:

ai-hub-cli --url "https://your-ai-hub.example.com" --api-key "your-api-key-here" [command]

Global flags (all commands)

--self-update — On startup, check for a newer binary and optionally refresh on an interval.
--self-update-interval — Interval for periodic checks (default 1h; e.g. 30m, 2h).

AI Hub API commands

These commands use AI_HUB_URL and AI_HUB_API_KEY to talk to your hub’s HTTP API and MCP endpoint.

`connect`

Connects to the hub MCP URL (…/api/mcp), initializes if possible, and prints available tools in a table. Useful for a quick sanity check.

ai-hub-cli connect

`tools` and `call`

tools lists tools from the hub’s MCP tools/list (add --json for machine-readable output). call invokes a tool by name; pass JSON arguments with --params.

ai-hub-cli tools
ai-hub-cli tools --json
ai-hub-cli call my_tool --params '{"key":"value"}'

`files`

ai-hub-cli files list <workspace-id>
ai-hub-cli files get <workspace-id> <file-id>
ai-hub-cli files download <workspace-id> <file-id> <output-path>

`mount`

Mount a workspace at a path (FUSE). Examples:

ai-hub-cli mount <workspace-id> /mnt/aihub

ai-hub-cli mount <workspace-id> M:

Pick a free drive letter (or another supported mount point after installing WinFsp). WSL users can use the Linux example with a Linux path.

FUSE requirements:

Linux: FUSE is usually available out of the box.
macOS: Install macFUSE.
Windows: Install WinFsp.

Update the CLI

Downloads the latest binary for your OS/arch from the official bucket (or a custom base URL) and replaces the running executable. Cache metadata avoids redundant downloads when nothing changed.

ai-hub-cli update

Override download location: set AI_HUB_CLI_S3_URL or pass --s3-url to update (same default bucket as this page: https://ai-hub-cli.s3.de.io.cloud.ovh.net). Use sudo ai-hub-cli update if the binary lives in a system directory.

Local MCP executors

These commands start stdio MCP servers on their own—use them with AI Hub via ai-hub-cli mcp … (see MCP registration) or any MCP-capable client.

Python executor

ai-hub-cli python-executor

Tool: execute_python — sandboxed Python with persistent state; optional dependencies and output_file_paths. UV manages venvs when available.

Terminal executor

ai-hub-cli terminal-executor

Tool: execute_terminal — foreground or background commands, optional working directory.

Combined executor

ai-hub-cli combined-executor

Both Python and terminal tools in one MCP server (matches the default Docker image behavior).

ACP connector

Bridges the Agent Client Protocol (ACP) to local agent processes over stdio. Optional JSON config lists agent profiles (id, command, args, description).

# Example: config from file (env ACP_AGENTS_CONFIG) or flag
ai-hub-cli acp-connector --acp-agents-config /path/to/agents.json --workspace /path/to/project

# agents.json shape: { "agents": [ { "id": "...", "command": "...", "args": [], "description": "..." } ] }

Flags: --acp-agents-config (or ACP_AGENTS_CONFIG), --workspace (default working directory for path validation; default cwd), --acp-auto-approve (default true — auto-approve session / permission prompts from the agent).

`python-run` and `terminal-run`

Direct CLI wrappers around the same execution engines used by the MCP servers—handy for scripts and debugging without an MCP client.

ai-hub-cli python-run 'print(1 + 1)'
# See ai-hub-cli python-run --help for container/session flags and stdin.

ai-hub-cli terminal-run "echo hello"
ai-hub-cli terminal-run --background "npm run dev"
ai-hub-cli terminal-run --working-dir /path/to/repo "ls -la"

Database connectors

Each connector runs as an MCP server with an execute_sql tool. Connection settings can be passed as flags or environment variables (flags win). Examples below are abbreviated; see --help on each subcommand for the full set.

SQLite

# Using CLI flags
ai-hub-cli sqlite-connector --dbpath /path/to/database.db

# Using environment variables
export SQLITE_DB_PATH=/path/to/database.db
ai-hub-cli sqlite-connector

# In-memory database (default)
ai-hub-cli sqlite-connector

Tools: execute_sql

PostgreSQL

# Using CLI flags
ai-hub-cli postgres-connector --host localhost --port 5432 --user postgres --password mypass --dbname mydb

# Using environment variables
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=mypass
export POSTGRES_DB=mydb
ai-hub-cli postgres-connector

# Using DSN
ai-hub-cli postgres-connector --dsn "host=localhost port=5432 user=postgres password=mypass dbname=mydb sslmode=disable"

Tools: execute_sql

MySQL

# Using CLI flags
ai-hub-cli mysql-connector --host localhost --port 3306 --user root --password mypass --dbname mydb

# Using environment variables
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=mypass
export MYSQL_DB=mydb
ai-hub-cli mysql-connector

# Using DSN
ai-hub-cli mysql-connector --dsn "user:password@tcp(localhost:3306)/mydb?charset=utf8mb4&parseTime=true"

Tools: execute_sql

MS SQL Server

# Using CLI flags
ai-hub-cli mssql-connector --host localhost --port 1433 --user sa --password mypass --database mydb

# Using environment variables
export MSSQL_HOST=localhost
export MSSQL_PORT=1433
export MSSQL_USER=sa
export MSSQL_PASSWORD=mypass
export MSSQL_DATABASE=mydb
ai-hub-cli mssql-connector

# Using DSN
ai-hub-cli mssql-connector --dsn "server=localhost;port=1433;user id=sa;password=mypass;database=mydb;encrypt=disable"

Tools: execute_sql

ClickHouse

# Using CLI flags
ai-hub-cli clickhouse-connector --host localhost --port 9000 --user default --password mypass --database default

# Using environment variables
export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=9000
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=mypass
export CLICKHOUSE_DATABASE=default
ai-hub-cli clickhouse-connector

# Using DSN
ai-hub-cli clickhouse-connector --dsn "clickhouse://user:password@localhost:9000/default?secure=false"

Tools: execute_sql

Oracle

# Using CLI flags (with SERVICE_NAME - preferred)
ai-hub-cli oracle-connector --host localhost --port 1521 --user myuser --password mypass --service MY_SERVICE

# Using CLI flags (with SID - legacy)
ai-hub-cli oracle-connector --host localhost --port 1521 --user myuser --password mypass --sid MY_SID

# Using environment variables
export ORACLE_HOST=localhost
export ORACLE_PORT=1521
export ORACLE_USER=myuser
export ORACLE_PASSWORD=mypass
export ORACLE_SERVICE=MY_SERVICE
ai-hub-cli oracle-connector

# Using DSN
ai-hub-cli oracle-connector --dsn "myuser/mypass@localhost:1521/MY_SERVICE"

Tools: execute_sql

Oracle: Requires Oracle Instant Client on the machine. Builds without CGO omit Oracle support.

REST connector

Exposes REST endpoints from an OpenAPI 3.0 spec (JSON or YAML) as MCP tools. Each operation becomes a callable tool; HTTP method, path/query/header parameters, and bodies are mapped from the spec.

Basic usage

# With OpenAPI specification and base URL
ai-hub-cli rest-connector --spec openapi.json --base-url https://api.example.com

# Base URL can also be taken from OpenAPI `servers` if omitted
ai-hub-cli rest-connector --spec openapi.json

Authentication

# Bearer token (Authorization header)
ai-hub-cli rest-connector --spec openapi.json --base-url https://api.example.com --api-key YOUR_API_KEY

# Custom API key header
ai-hub-cli rest-connector --spec openapi.json --base-url https://api.example.com --api-key YOUR_API_KEY --api-key-header X-API-Key

Highlights:

OpenAPI 3.0 — GET, POST, PUT, DELETE, PATCH
Path, query, header, and body parameters from the spec
Tool names from operationId or path + method
JSON request bodies and structured responses

Filesystem connector

Exposes one or more directories as MCP resources (filesystem://…) and file-operation tools. Use --path for the primary root (unprefixed paths refer to it). Add extra host folders with repeated --volume / -v NAME=ABSOLUTE_PATH (Docker-style bind mounts); those files appear under NAME/… and as filesystem://NAME/…. Access is confined to those roots.

Basic usage (single folder)

ai-hub-cli filesystem-connector --path /home/you/project

ai-hub-cli filesystem-connector --path C:\Users\you\project

Primary path + extra volumes

Combine --path with one or more -v NAME=PATH. Unprefixed paths use the primary; paths starting with NAME/ use that mount. If a volume name matches a top-level directory under the primary, the named mount wins and a warning is printed to stderr (MCP stdout stays clean for JSON-RPC).

ai-hub-cli filesystem-connector \
  --path /home/you/monorepo \
  -v frontend=/home/you/frontend-app \
  -v backend=/home/you/backend-api

ai-hub-cli filesystem-connector `
  --path C:\Users\you\monorepo `
  -v frontend=C:\Users\you\frontend-app `
  -v backend=C:\Users\you\backend-api

ai-hub-cli filesystem-connector ^
  --path C:\Users\you\monorepo ^
  -v frontend=C:\Users\you\frontend-app ^
  -v backend=C:\Users\you\backend-api

Named volumes only (no `--path`)

You can run with only -v entries; every path must then use a volume prefix (e.g. frontend/src/App.tsx).

ai-hub-cli filesystem-connector -v app=/srv/myapp -v data=/var/data

ai-hub-cli filesystem-connector -v app=C:\srv\myapp -v data=D:\data

Permissions

Default is read-only. Use --permission and optionally --tools:

--permission read-only — search, read, list, info, glob (default)
--permission full — includes write, delete, move, copy, create directory
--tools search_files,read_file,… — allowlist of tool names

ai-hub-cli filesystem-connector --path /path/to/folder
ai-hub-cli filesystem-connector --path /path/to/folder --permission full
ai-hub-cli filesystem-connector --path /path/to/folder --tools search_files,read_file,list_directory

ai-hub-cli filesystem-connector --path C:\path\to\folder
ai-hub-cli filesystem-connector --path C:\path\to\folder --permission full
ai-hub-cli filesystem-connector --path C:\path\to\folder --tools search_files,read_file,list_directory

Tools include: search_files, read_file, write_file, delete_file, move_file, copy_file, create_directory, list_directory, get_file_info, glob_files. Resources support list/read, subscriptions where the client allows, path completion, and MCP annotations for safe UIs. Cross-root move_file is rejected (use copy + delete instead).

Security: Path validation blocks directory traversal; all operations stay under the configured primary and named roots.

MCP registration with AI Hub

Register a local MCP server (stdio)

The mcp subcommand starts a built-in connector or any following command as stdio MCP and registers it with AI Hub. Arguments after the server name are forwarded.

ai-hub-cli mcp postgres-connector --host localhost --port 5432 --user postgres --password mypass

Remote HTTP MCP (streamable HTTP)

Use an http:// or https:// URL instead of a subcommand name. The CLI uses the MCP streamable-HTTP transport, with optional headers for auth.

Basic

ai-hub-cli mcp https://remote-mcp-server.example.com/mcp
ai-hub-cli mcp http://localhost:8080/mcp
ai-hub-cli mcp https://api.example.com:8443/mcp

Authentication headers

ai-hub-cli mcp --mcp-header "Authorization: Bearer your-token-here" https://remote-mcp-server.example.com/mcp
ai-hub-cli mcp --mcp-header "X-API-Key: your-api-key" https://remote-mcp-server.example.com/mcp

Multiple headers

ai-hub-cli mcp \
  --mcp-header "Authorization: Bearer token123" \
  --mcp-header "X-Custom-Header: value" \
  https://remote-mcp-server.example.com/mcp

Notes: Auto-detects HTTP(S) and uses streamable HTTP; continuous listening for server notifications is enabled by default. Repeat --mcp-header for each header. Prefer HTTPS in production; keep secrets out of shell history where possible.

Requirements: The remote server must implement the MCP streamable-HTTP spec. Use the path your server documents (often /mcp).

Docker

Images are published to GitHub Container Registry on pushes to main and on version tags. The default entrypoint runs the combined executor MCP server.

docker pull ghcr.io/clye-gmbh/ai-hub-cli:latest
docker run -e AI_HUB_URL="https://your-ai-hub.example.com" \
           -e AI_HUB_API_KEY="your-api-key-here" \
           ghcr.io/clye-gmbh/ai-hub-cli:latest

Tags: latest, v* releases, main-<sha> for main-branch builds. Override the container command to run other subcommands or connectors.

Install from source

go install github.com/clye-gmbh/ai-hub-cli@latest

Or clone the repo and go build -o ai-hub-cli main.go. For a portable static binary without Oracle, use CGO_ENABLED=0 (see project README).

🚀 AI Hub CLI

Features

Quick install

Manual download

Configuration

Environment variables

Command-line flags

Global flags (all commands)

AI Hub API commands

connect

tools and call

files

mount

Update the CLI

Local MCP executors

Python executor

Terminal executor

Combined executor

ACP connector

python-run and terminal-run

Database connectors

SQLite

PostgreSQL

MySQL

MS SQL Server

ClickHouse

Oracle

REST connector

Basic usage

Authentication

Filesystem connector

Basic usage (single folder)

Primary path + extra volumes

Named volumes only (no --path)

Permissions

MCP registration with AI Hub

Register a local MCP server (stdio)

Remote HTTP MCP (streamable HTTP)

Basic

Authentication headers

Multiple headers

Docker

Install from source

`connect`

`tools` and `call`

`files`

`mount`

`python-run` and `terminal-run`

Named volumes only (no `--path`)