Connect Commands¶

Commands and global flags for connecting to a provider, agent, or runtime.

Overview¶

SuperQode provides two ways to connect:

• --connect / -C global flag -- set the connection profile on startup.
• superqode connect command group -- explicit CLI connect commands, setup guides, and agent connections.

--connect / -C Global Flag¶

Select a connection profile directly from the CLI.

superqode --connect PROFILE [COMMAND]
superqode -C PROFILE [COMMAND]

Choices¶

Self-Contained Profiles¶

codex and antigravity are self-contained profiles. Copilot dynamically selects an installed official integration:

• --connect codex sets runtime to codex-sdk
• --connect copilot prefers copilot-sdk, otherwise starts copilot --acp --stdio
• --connect antigravity sets runtime to antigravity-cli

Claude Pro and Max are not connection profiles because Anthropic documents those subscriptions for its first-party clients and bills API usage separately. Use --runtime claude-agent-sdk or --connect byok anthropic <model> with an Anthropic API key.

Examples¶

# Start the TUI connected to Anthropic
superqode --connect byok anthropic <anthropic-model>

# Run a headless task via Codex
superqode --connect codex -p "explain this project"

# Run a headless task via GitHub Copilot SDK
superqode --connect copilot -p "review this project"

# Advanced compatibility path through the Copilot CLI ACP server
superqode connect acp copilot

# Run a headless task via the Claude Agent SDK API-key route
superqode --runtime claude-agent-sdk -p "refactor this module"

# Connect to a local model
superqode --connect local ollama qwen3:8b

# Connect to an ACP agent
superqode --connect acp opencode

# Run Antigravity with your existing Google Sign-In
superqode --connect antigravity

# Connect SuperQode harness on your Grok subscription (official CLI login)
superqode --connect grok

# Grok Build as an external ACP agent (same CLI login, different product)
superqode --connect acp grok

Connection Profiles¶

codex¶

Uses the Codex SDK as the runtime backend.

copilot¶

Uses a signed-in GitHub Copilot plan. Install superqode[copilot-sdk] for SuperQode-native harness controls, or install @github/copilot for the ACP route. If both are present, the SDK is preferred and reuses the installed CLI. Authenticate with copilot login or COPILOT_GITHUB_TOKEN. From inside the TUI, :copilot login starts the official device flow after a confirmation and keeps the URL/code visible in the current terminal.

:connect copilot
:copilot login
:copilot models
:copilot model <id>
:copilot mode [agent|plan|autopilot]
:copilot sessions

:copilot mode is a CLI/ACP session control and works on every Copilot plan. :copilot models and :copilot model depend on what the signed-in account advertises; plans that advertise no catalog let Copilot choose the model.

Use :copilot sdk or :copilot cli to override automatic selection. :connect acp copilot and the old :connect copilot-acp shortcut remain accepted for compatibility but are hidden from normal discovery. See GitHub Copilot for the ownership and capability differences.

antigravity¶

Uses the official agy CLI in headless print mode. Authentication stays inside agy: run it once to complete Google Sign-In, after which it reads the session from the OS keyring. SuperQode requires agy 1.1.1 or newer. For API keys, use :connect byok google or the optional antigravity-sdk advanced runtime.

See Google Antigravity for the harness ownership matrix and the supported CLI, SDK, and SuperQode harness routes.

grok¶

Runs Grok Build, xAI's own coding agent, on your Grok subscription over ACP (grok agent stdio). The vendor's agent owns the loop.

To run SuperQode's own harness on the same subscription instead, use :grok api [model]: it imports the CLI session into ~/.superqode/auth.json and routes through the grok-cli provider (CLI chat proxy). The grok-cli runtime (:runtime grok-cli) is the headless grok -p path and is not what :connect grok opens. See xAI Grok and BYOK Providers.

byok¶

Bring Your Own Key. Connect to any supported cloud provider using your own API key. The CLI command requires a provider and model. The TUI :connect byok command can open interactive pickers.

local¶

Connect to a local or self-hosted provider (Ollama, MLX, LM Studio, vLLM, DS4, etc.). The CLI command requires a provider and model. The TUI :connect local command can open interactive pickers.

acp¶

Connect to any ACP-compatible coding agent installed on your system. The CLI command requires an agent name. The TUI :connect acp command can open an interactive picker. Installed agents are listed first, followed by the curated featured catalog. Use :connect acp enterprise for enterprise runtimes and :connect acp all for the complete registry.

superqode connect¶

The superqode connect command group provides subcommands for connecting to providers, agents, and runtimes, as well as viewing setup guides.

superqode connect COMMAND [OPTIONS] [ARGS]

Subcommands¶

connect uhp¶

Connect to a Unified Harness Protocol server, discover the harnesses it advertises, and select one.

superqode connect uhp [OPTIONS]

Options¶

Examples¶

superqode connect uhp --base-url https://your-server
superqode connect uhp --harness chrn_claude
superqode connect uhp --json

Notes¶

A UHP server is a remote catalog, so the address is resolved before the harness list is known. Settings come from options first, then SUPERQODE_UHP_BASE_URL and SUPERQODE_UHP_API_KEY, then the saved connection at ~/.superqode/uhp.json.

See Unified Harness Protocol for the adapter, the event mapping, and the capability list.

connect a2a¶

Connect to an A2A agent, fetch its Agent Card, and optionally send one message. The client speaks the first advertised interface it can: JSON-RPC 1.0, JSON-RPC 0.3, or HTTP+JSON 1.0.

superqode connect a2a [OPTIONS]

Options¶

Examples¶

superqode connect a2a --url https://agent.example
superqode connect a2a --url https://agent.example --inspect
superqode connect a2a --url https://agent.example --conformance
superqode connect a2a --url https://agent.example --conformance --no-send
superqode connect a2a --url https://agent.example --header "X-Tenant: acme"
superqode connect a2a --url https://agent.example --send "Which coding agents are open source?"
superqode connect a2a --url https://localhost:8000 --token "$SUPERQODE_A2A_CLIENT_TOKEN"
superqode connect a2a --url https://agent.example --logout

Notes¶

Settings come from options first, then SUPERQODE_A2A_URL and SUPERQODE_A2A_CLIENT_TOKEN (or SUPERQODE_A2A_TOKEN), then ~/.superqode/a2a.json. A token that came from the environment is never copied to that file.

OAuth browser login always redirects to http://localhost:19876/a2a/oauth/callback. Register that URI with the identity provider and set SUPERQODE_A2A_OAUTH_CLIENT_ID (and SUPERQODE_A2A_OAUTH_CLIENT_SECRET for a confidential client) unless the authorization server supports dynamic client registration. Tokens are stored in the OS keyring when one is available, otherwise under ~/.superqode/a2a-oauth/. --logout deletes them and calls the authorization server's revocation_endpoint when that was stored at login. A query-string API key is sent on the request URL; pass it as --token when the card names that scheme. Mutual TLS uses --tls-cert and --tls-key (or SUPERQODE_A2A_TLS_CERT / SUPERQODE_A2A_TLS_KEY).

From the TUI, :connect → Protocols → A2A (or :connect a2a) opens a screen for the origin plus credential, extra headers, mTLS paths, and an OAuth on/skip control. A bare :connect a2a <url> or :a2a connect <url> opens that screen with the origin filled in. Open cards leave the credential empty. OAuth opens a browser. Logout clears stored tokens. After Connect, Send is the chat with that agent and keeps the same contextId thread. Skill examples fill the message box. Use saves the connection in place; Back returns. y copies, r resends, Esc stops a wait. The screen lists skills and an inspect pane for the binding choice, advertised auth, and HTTP. --inspect is the CLI form of that pane. --conformance runs four client checks (card-fetch, card-shape, binding, send) and does not save the connection. A card SuperQode cannot speak prints the advertised interfaces and why each one was skipped. These checks answer whether SuperQode can talk to the card. They are not an A2A specification suite.

See A2A Protocol.

connect acp¶

Connect to an ACP (Agent Client Protocol) coding agent by short name.

superqode connect acp AGENT [OPTIONS]

Arguments¶

Options¶

Examples¶

# Connect to OpenCode
superqode connect acp opencode

# Connect with a custom project directory
superqode connect acp opencode --project-dir /path/to/project
superqode connect acp opencode -d /path/to/project

Notes¶

This command launches a simple CLI interactive session. For the full TUI experience, run superqode and use :connect acp <agent> inside the TUI.

The TUI also supports:

:connect acp                 # installed and featured agents
:connect acp enterprise      # enterprise agents
:connect acp all             # complete registry and SuperQode adapters
:connect acp refresh         # refresh the official registry cache

connect byok¶

Connect to a cloud provider using your own API key. Provider and model are required in the CLI command. Use the TUI :connect byok picker when you want interactive provider and model selection.

superqode connect byok PROVIDER MODEL

Arguments¶

Examples¶

# Full inline specification
superqode connect byok anthropic <anthropic-model>

# Hugging Face Inference Provider route
superqode connect byok huggingface zai-org/GLM-5.2:fireworks-ai
superqode connect byok hf.zai-org/GLM-5.2:together

# For interactive selection, use the TUI
superqode
# then type: :connect byok

For Hugging Face Inference Providers, hf.<repo>:<provider>, hf/<repo>:<provider>, and huggingface/<repo>:<provider> are accepted and normalize to the huggingface provider. GLM-5.2 aliases include glm52, glm52-hf-fireworks, glm52-hf-together, glm52-hf-novita, glm52-hf-zai, and glm52-hf-deepinfra.

First-party Z.AI route¶

export ZAI_API_KEY=your-general-api-key
superqode connect zai glm-5.2

This uses Z.AI's general API endpoint. It does not consume GLM Coding Plan subscription quota. In the TUI, use :connect zai or :connect zai/glm-5.2. The model alias glm52-zai resolves to the same first-party route.

connect local¶

Connect to a local or self-hosted provider. The CLI command requires both provider and model. Use the TUI :connect local picker when you want interactive provider and model selection.

superqode connect local PROVIDER MODEL

Arguments¶

Examples¶

# Full inline specification
superqode connect local ollama qwen3:8b

# For interactive selection, use the TUI
superqode
# then type: :connect local

connect setup¶

Show a setup guide for any of the 130+ supported providers. Displays required environment variables, base URL, documentation URL, example models, and the exact connect command.

superqode connect setup PROVIDER [OPTIONS]

Arguments¶

Options¶

Examples¶

# Show setup guide for Anthropic
superqode connect setup anthropic

# Show setup guide for Ollama
superqode connect setup ollama

# Show setup guide for DeepSeek as JSON
superqode connect setup deepseek --json

Output¶

Provider: Anthropic
Category: US Labs
Tier: Tier 1

Environment Variables:
  ANTHROPIC_API_KEY (required)

Base URL: https://api.anthropic.com
Documentation: https://docs.anthropic.com/

Example Models:
  - <anthropic-model>
  - <anthropic-balanced-model>
  - <anthropic-fast-model>

Connect Command:
  superqode connect byok anthropic <model>

Related Commands¶

• superqode providers list - List available providers
• superqode providers test - Test provider connection
• superqode agents list - List installed ACP agents
• superqode auth info - Show authentication status