Download docs/quickstart/cli/getting-started.mdx from shimen/yapapaway: direct link, hf CLI and curl.
- Browser
- Download file 12.3 kB
-
https://huggingface.co/spaces/shimen/yapapaway/resolve/main/docs/quickstart/cli/getting-started.mdx
- Command line
-
hf download hf://spaces/shimen/yapapaway/docs/quickstart/cli/getting-started.mdx
-
curl -L -o getting-started.mdx https://huggingface.co/spaces/shimen/yapapaway/resolve/main/docs/quickstart/cli/getting-started.mdx
12.3 kB
| --- | |
| title: "Bifrost CLI" | |
| description: "Launch any coding agent through Bifrost with a single command. Automatic configuration, model selection, and MCP integration β no environment variables needed." | |
| icon: "laptop-code" | |
| --- | |
| {/* TODO: Add hero screenshot of the CLI TUI showing the summary/launch screen */} | |
| ## What is Bifrost CLI? | |
| <Frame> | |
| <iframe | |
| src="https://drive.google.com/file/d/1Sh1-xCJrVeccKscaowznopHNdyoGl2zu/preview" | |
| title="Embedded content" | |
| className="w-full h-96 rounded-md" | |
| ></iframe> | |
| </Frame> | |
| Bifrost CLI is an interactive terminal tool that connects your favorite coding agents β Claude Code, Codex CLI, Gemini CLI, and Opencode β to your Bifrost gateway with zero manual configuration. | |
| Instead of setting environment variables, editing config files, and looking up provider paths, you just run `bifrost` and pick your agent, model, and go. | |
| **What it does for you:** | |
| - Automatically configures base URLs, API keys, and model settings for each agent | |
| - Fetches available models from your Bifrost gateway's `/v1/models` endpoint | |
| - Installs missing agents via npm if needed | |
| - Auto-attaches Bifrost's MCP server to Claude Code for tool access | |
| - Launches agents inside a persistent tabbed terminal UI so you can switch sessions without re-running the CLI | |
| - Shows per-tab activity badges so you can tell when a session is progressing, idle, or has sent an alert | |
| - Stores your selections securely (virtual keys go to your OS keyring, never plaintext on disk) | |
| ## Installation | |
| ```bash | |
| npx -y @maximhq/bifrost-cli | |
| ``` | |
| This downloads and runs the latest Bifrost CLI. No global install required β npx handles everything. | |
| <Note> | |
| Bifrost CLI requires **Node.js 18+** (for npx) and a running Bifrost gateway. See [Gateway Setup](/quickstart/gateway/setting-up) if you haven't started one yet. | |
| </Note> | |
| ### Install a Specific Version | |
| ```bash | |
| npx -y @maximhq/bifrost-cli --cli-version v1.0.0 | |
| ``` | |
| ## Quick Start | |
| ### 1. Start your Bifrost gateway | |
| Make sure your Bifrost gateway is running. The default is `http://localhost:8080`: | |
| ```bash | |
| npx -y @maximhq/bifrost | |
| ``` | |
| ### 2. Launch the CLI | |
| In another terminal: | |
| To install | |
| ```bash | |
| npx -y @maximhq/bifrost-cli | |
| ``` | |
| If you have already installed run | |
| ```bash | |
| bifrost | |
| ``` | |
| <Frame> | |
| <img src="/media/cli/welcome-screen.png" alt="CLI welcome screen" /> | |
| </Frame> | |
| ### 3. Walk through the setup | |
| The CLI guides you through an interactive setup flow: | |
| **Step 1 β Base URL** | |
| Enter your Bifrost gateway URL. If you're running locally, this is typically `http://localhost:8080`. | |
| {/* TODO: Add screenshot of the base URL input screen */} | |
| **Step 2 β Virtual Key (optional)** | |
| If your Bifrost gateway has [virtual key authentication](/features/governance/virtual-keys) enabled, enter your virtual key here. Otherwise, press Enter to skip. | |
| {/* TODO: Add screenshot of the virtual key input screen */} | |
| **Step 3 β Choose a Harness** | |
| Select which coding agent you want to launch. The CLI shows installation status and version for each: | |
| {/* TODO: Add screenshot of the harness selection screen */} | |
| | Harness | Binary | Provider Path | Notes | | |
| |---------|--------|---------------|-------| | |
| | Claude Code | `claude` | `/anthropic` | MCP auto-attach, worktree support | | |
| | Codex CLI | `codex` | `/openai` | Sets `OPENAI_BASE_URL` to `{base}/openai/v1`; model override via `--model` | | |
| | Gemini CLI | `gemini` | `/genai` | Model override via `--model` flag | | |
| | Opencode | `opencode` | `/openai` | Custom models configured automatically through generated OpenCode config | | |
| If a harness isn't installed, the CLI will offer to install it via npm for you. | |
| {/* TODO: Add screenshot of the install confirmation dialog */} | |
| **Step 4 β Select a Model** | |
| The CLI fetches available models from your Bifrost gateway and presents a searchable list. Type to filter, arrow keys to navigate: | |
| {/* TODO: Add screenshot of the model search/selection screen */} | |
| <Tip> | |
| You can type any model name manually β even if it's not in the list. Just type the full model identifier and press Enter. | |
| </Tip> | |
| **Step 5 β Launch** | |
| Review your configuration in the summary screen. Press Enter to launch, or use the shortcut keys to adjust any setting: | |
| {/* TODO: Add screenshot of the summary/ready-to-launch screen */} | |
| | Key | Action | | |
| |-----|--------| | |
| | `Enter` | Launch the harness | | |
| | `u` | Change base URL | | |
| | `v` | Change virtual key | | |
| | `h` | Change harness | | |
| | `m` | Change model | | |
| | `w` | Set worktree name (Claude Code only) | | |
| | `d` | Open Bifrost dashboard | | |
| | `r` | Open documentation | | |
| | `l` | Toggle harness exit logs | | |
| | `i` | Report an issue on GitHub | | |
| | `s` | Star the repo on GitHub | | |
| | `q` | Quit | | |
| The CLI then launches your agent with all the correct environment variables and configuration set automatically. | |
| {/* TODO: Add screenshot of the launch banner showing endpoint, model, vk status */} | |
| ## Tabbed Session UI | |
| After launch, Bifrost CLI keeps you inside a tabbed terminal UI instead of exiting after the first session. The bottom tab bar shows: | |
| - The `Bifrost CLI` label and current CLI version | |
| - One tab per running or recent agent session | |
| - A status badge for each tab: | |
| - `π§ ` β the visible screen is actively changing, so the agent is still working | |
| - `β ` β the session looks idle and ready | |
| - `π` β the PTY emitted a real terminal alert | |
| Use `Ctrl+B` at any time to focus the tab bar. From tab mode you can: | |
| | Key | Action | | |
| |-----|--------| | |
| | `n` | Open a new tab and launch another agent session | | |
| | `x` | Close the current tab | | |
| | `h` / `l` | Move left or right across tabs | | |
| | `1`-`9` | Jump directly to a tab | | |
| | `Esc` / `Enter` / `Ctrl+B` | Return to the active session | | |
| <Tip> | |
| If you press `Ctrl+B` before launching your first session, Bifrost CLI stays open on the Home tab bar so you can create a new tab from there. | |
| </Tip> | |
| ## Configuration | |
| ### Config File | |
| The CLI stores its configuration at `~/.bifrost/config.json`. This file is created automatically on first run and updated when you change settings through the TUI. | |
| ```json | |
| { | |
| "base_url": "http://localhost:8080", | |
| "default_harness": "claude", | |
| "default_model": "anthropic/claude-sonnet-4-5-20250929" | |
| } | |
| ``` | |
| | Field | Description | | |
| |-------|-------------| | |
| | `base_url` | Your Bifrost gateway URL | | |
| | `default_harness` | Last used harness ID (`claude`, `codex`, `gemini`, `opencode`) | | |
| | `default_model` | Last used model identifier | | |
| <Warning> | |
| Never put your virtual key in the config file. The CLI stores virtual keys securely in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service). | |
| </Warning> | |
| ### CLI Flags | |
| ```bash | |
| npx -y @maximhq/bifrost-cli [flags] | |
| ``` | |
| | Flag | Description | | |
| |------|-------------| | |
| | `-config <path>` | Path to a custom `config.json` file | | |
| | `-no-resume` | Skip resume flow and open fresh setup | | |
| | `-worktree <name>` | Create a git worktree for the session (Claude Code only) | | |
| ### Using a Custom Config Path | |
| Point the CLI to a project-specific config: | |
| ```bash | |
| npx -y @maximhq/bifrost-cli -config ./my-project/bifrost.json | |
| ``` | |
| This is useful when working across multiple Bifrost gateways or projects with different configurations. | |
| ## Switching Harnesses and Models | |
| The CLI handles all environment variables, API keys, and provider-specific configuration automatically β you never need to set them yourself. To change your setup, use the shortcut keys from the summary screen: | |
| {/* TODO: Add screenshot of the summary/ready-to-launch screen with shortcut keys highlighted */} | |
| | Key | Action | | |
| |-----|--------| | |
| | `h` | Switch to a different harness (Claude Code, Codex, Gemini CLI, Opencode) | | |
| | `m` | Pick a different model from the gateway's available models | | |
| | `u` | Change the Bifrost gateway URL | | |
| | `v` | Update your virtual key | | |
| | `w` | Set worktree name (Claude Code only) | | |
| | `d` | Open the Bifrost dashboard in your browser | | |
| | `r` | Open the CLI documentation | | |
| | `l` | Toggle harness exit logs | | |
| | `i` | Report an issue on GitHub | | |
| | `s` | Star the repo on GitHub | | |
| | `Enter` | Launch with current settings | | |
| | `q` | Quit | | |
| When you switch harnesses, the CLI reconfigures everything for the new agent β base URLs, API keys, model flags, and any agent-specific setup. You can switch as many times as you like before launching. | |
| <Tip> | |
| After a session ends, the CLI returns to the summary screen with your previous configuration intact. Press `h` to switch agents or `m` to try a different model, then `Enter` to re-launch. | |
| </Tip> | |
| ### Opencode Notes | |
| Bifrost CLI applies two OpenCode-specific behaviors automatically: | |
| - **Custom model selection**: when you pick a model in Bifrost CLI, OpenCode is launched with the correct provider-qualified model reference and a generated OpenCode runtime config. | |
| - **Theme handling**: if your OpenCode `tui.json` already defines a theme, Bifrost preserves it. If not, Bifrost supplies the adaptive `system` theme so OpenCode does not fall back to its default dark-only appearance. | |
| ## Session Flow | |
| The CLI is designed for iterative development sessions: | |
| 1. **Launch** β Select your agent and model, press Enter | |
| 2. **Work** β Use your agent as normal, all traffic routes through Bifrost | |
| 3. **Switch** β Press `Ctrl+B` any time to open the tab bar and jump to another session or start a new one | |
| 4. **Return** β When an agent exits (or you quit it), the CLI returns to the chooser with your previous configuration intact | |
| 5. **Re-launch** β Change model, switch harness, or re-launch the same setup instantly | |
| Your last selections are remembered across sessions. The next time you run `bifrost`, you'll see the summary screen with your previous configuration ready to go. Press Enter to re-launch immediately, or adjust any setting. | |
| {/* TODO: Add screenshot showing the re-launch flow with a previous session message */} | |
| ## Worktree Support | |
| <Note> | |
| Worktree support is currently available for **Claude Code** only. | |
| </Note> | |
| Launch Claude Code in an isolated git worktree for parallel development: | |
| ```bash | |
| npx -y @maximhq/bifrost-cli -worktree feature-branch | |
| ``` | |
| Or select worktree mode from the TUI during the setup flow. The CLI passes the `--worktree` flag to Claude Code automatically. | |
| ## MCP Integration | |
| When launching **Claude Code**, the CLI automatically registers Bifrost's MCP server endpoint (`/mcp`) so all your configured MCP tools are available inside the agent. | |
| If a virtual key is configured, the CLI sets up authenticated MCP access with the correct `Authorization` header β no manual `claude mcp add-json` commands needed. | |
| For other harnesses, the CLI prints the MCP server URL so you can configure it manually in your agent's settings. | |
| ## Troubleshooting | |
| ### "npm not found in path" | |
| The CLI needs npm to install harnesses. Make sure Node.js is installed: | |
| ```bash | |
| node --version # Should be 18+ | |
| npm --version | |
| ``` | |
| ### Agent not found after install | |
| If a harness was installed but the binary still isn't found, you may need to restart your terminal or add npm's global bin directory to your `PATH`: | |
| ```bash | |
| # Check npm global bin path | |
| npm config get prefix | |
| # Add to PATH (add to ~/.zshrc or ~/.bashrc for persistence) | |
| export PATH="$(npm config get prefix)/bin:$PATH" | |
| ``` | |
| ### Models not loading | |
| If the model list doesn't load, check that: | |
| 1. Your Bifrost gateway is running and accessible at the configured base URL | |
| 2. You have at least one provider configured in Bifrost | |
| 3. If using virtual keys, your key has permission to list models | |
| ### Virtual key not persisting | |
| The CLI stores virtual keys in your OS keyring. On Linux, ensure `gnome-keyring` or `kwallet` is running. If keyring access fails, the CLI will log a warning but continue working β the key will need to be re-entered next session. | |
| ## Next Steps | |
| <CardGroup cols={2}> | |
| <Card title="Gateway Setup" icon="server" href="/quickstart/gateway/setting-up"> | |
| Set up a Bifrost gateway if you haven't already | |
| </Card> | |
| <Card title="Provider Configuration" icon="gear" href="/quickstart/gateway/provider-configuration"> | |
| Configure AI providers in your Bifrost gateway | |
| </Card> | |
| <Card title="Virtual Keys" icon="key" href="/features/governance/virtual-keys"> | |
| Set up authentication and usage limits | |
| </Card> | |
| <Card title="MCP Gateway" icon="toolbox" href="/mcp/overview"> | |
| Configure MCP tools for your agents | |
| </Card> | |
| </CardGroup> | |