CLI Reference

Complete command-line reference for Bifrost server and client.

Server Commands

bifrost-server

Main server executable.

bifrost-server [flags]
bifrost-server [command]

Global Flags

Flag	Short	Default	Description
`--config`	`-c`	`server-config.yaml`	Configuration file path
`--help`	`-h`		Show help

Commands

Command	Description
`completion`	Generate shell autocompletion scripts
`ctl`	Control a running server
`help`	Help about any command
`update`	Check for and install updates
`validate`	Validate configuration file
`version`	Print version information

bifrost-server validate

Validate a configuration file without starting the server.

bifrost-server validate -c config.yaml

Exit codes:

0 - Configuration is valid
1 - Configuration has errors

bifrost-server version

Print version information.

bifrost-server version

Output:

Bifrost Server v1.0.0
  Commit: abc1234
  Built: 2024-01-15T10:00:00Z
  Go: go1.22.0
  OS/Arch: linux/amd64

bifrost-server update

Check for and install updates.

bifrost-server update [command] [flags]

Flags

Flag	Short	Default	Description
`--channel`		`stable`	Release channel (stable, prerelease)
`--force`	`-f`	`false`	Force update even if same version

Subcommands

update check

Check if updates are available without installing.

bifrost-server update check

Output:

Update available!
  Current version: v1.0.0
  New version:     v1.1.0
  Published:       Mon, 15 Jan 2024 10:00:00 UTC
  Release URL:     https://github.com/rennerdo30/bifrost-proxy/releases/tag/v1.1.0

Run 'bifrost-server update install' to install.

update install

Download and install the latest update.

bifrost-server update install

Features:

Downloads from GitHub Releases
Verifies SHA256 checksum
Creates backup before replacing
Shows download progress

Note: The server must be restarted after updating.

bifrost-server ctl

Control a running Bifrost server via the API.

bifrost-server ctl [command] [flags]

Flags

Flag	Default	Description
`--api`	`http://localhost:7082`	API server URL
`--token`		API authentication token

Subcommands

ctl health

Check server health.

bifrost-server ctl health

ctl status

Show server status.

bifrost-server ctl status

ctl stats

Show server statistics.

bifrost-server ctl stats

ctl backend

Manage backends.

# List all backends
bifrost-server ctl backend list

# Show specific backend
bifrost-server ctl backend show <name>

# Show backend stats
bifrost-server ctl backend stats <name>

ctl config

Manage configuration.

# Show current config
bifrost-server ctl config show

# Reload configuration
bifrost-server ctl config reload

# Validate configuration
bifrost-server ctl config validate

Client Commands

bifrost-client

Main client executable.

bifrost-client [flags]
bifrost-client [command]

Global Flags

Flag	Short	Default	Description
`--config`	`-c`	`client-config.yaml`	Configuration file path
`--help`	`-h`		Show help

Commands

Command	Description
`completion`	Generate shell autocompletion scripts
`config`	Configuration management
`ctl`	Control a running client
`help`	Help about any command
`update`	Check for and install updates
`validate`	Validate configuration file
`version`	Print version information

bifrost-client config

Configuration management commands.

bifrost-client config [command]

config init

Generate a sample client configuration file.

bifrost-client config init [flags]

Flag	Short	Default	Description
`--server`	`-s`		Server address (host:port)
`--output`	`-o`	`client-config.yaml`	Output file path
`--protocol`	`-p`	`http`	Protocol (http, socks5)

Examples:

# Generate basic config
bifrost-client config init -s proxy.example.com:7080

# Specify output file
bifrost-client config init -s proxy.example.com:7080 -o my-config.yaml

# Use SOCKS5 protocol
bifrost-client config init -s proxy.example.com:7180 -p socks5

bifrost-client validate

Validate a configuration file.

bifrost-client validate -c config.yaml

bifrost-client version

Print version information.

bifrost-client version

bifrost-client update

Check for and install updates.

bifrost-client update [command] [flags]

Flags

Flag	Short	Default	Description
`--channel`		`stable`	Release channel (stable, prerelease)
`--force`	`-f`	`false`	Force update even if same version

Subcommands

update check

Check if updates are available without installing.

bifrost-client update check

update install

Download and install the latest update.

bifrost-client update install

Note: The client must be restarted after updating.

bifrost-client ctl

Control a running Bifrost client via the API.

bifrost-client ctl [command] [flags]

Flags

Flag	Default	Description
`--api`	`http://localhost:7383`	API server URL

Subcommands

ctl health

Check client health.

bifrost-client ctl health

ctl status

Show client status including server connection.

bifrost-client ctl status

ctl routes

List routing rules.

bifrost-client ctl routes

ctl test

Test routing for a domain.

bifrost-client ctl test example.com

Shell Completion

Generate autocompletion scripts for your shell.

Bash

# Generate completion script
bifrost-server completion bash > /etc/bash_completion.d/bifrost-server

# Or add to .bashrc
echo 'source <(bifrost-server completion bash)' >> ~/.bashrc

Zsh

# Generate completion script
bifrost-server completion zsh > "${fpath[1]}/_bifrost-server"

# Or add to .zshrc
echo 'source <(bifrost-server completion zsh)' >> ~/.zshrc

Fish

bifrost-server completion fish > ~/.config/fish/completions/bifrost-server.fish

PowerShell

bifrost-server completion powershell > bifrost-server.ps1

Environment Variables

Configuration can be set via environment variables using the ${VAR_NAME} syntax in config files.

Common Variables

Variable	Description	Example
`BIFROST_CONFIG`	Config file path	`/etc/bifrost/config.yaml`
`BIFROST_LOG_LEVEL`	Log level	`debug`, `info`, `warn`, `error`
`BIFROST_API_TOKEN`	API authentication token	`your-secret-token`

Authentication Variables

Variable	Description
`LDAP_BIND_PASSWORD`	LDAP bind password
`OAUTH_CLIENT_SECRET`	OAuth client secret

Example Usage

# config.yaml
api:
  token: "${BIFROST_API_TOKEN}"

auth:
  providers:
    - name: ldap
      type: ldap
      enabled: true
      priority: 1
      config:
        url: "ldaps://ldap.example.com:636"
        base_dn: "dc=example,dc=com"
        bind_dn: "cn=bifrost-svc,ou=services,dc=example,dc=com"
        bind_password: "${LDAP_BIND_PASSWORD}"

export BIFROST_API_TOKEN="my-secret-token"
export LDAP_BIND_PASSWORD="ldap-password"
bifrost-server -c config.yaml

Only ${VAR} and ${VAR:-fallback} are expanded; $$ yields a literal $. A bare $VAR is not expanded, and every other $ is literal, so a secret containing $ survives unchanged. See Configuration.

Loader Behavior

Variable	Description
`BIFROST_CONFIG_ALLOW_UNKNOWN_KEYS`	Set to `1` to downgrade unknown config keys from a startup failure to a warning. Transitional migration aid; see Configuration.

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error
3	Connection error

Examples

Start Server with Custom Config

bifrost-server -c /etc/bifrost/production.yaml

Validate Configuration

bifrost-server validate -c config.yaml && echo "Config OK"

Check Server Health

bifrost-server ctl health --api http://localhost:7082 --token mytoken

Generate Client Config and Start

bifrost-client config init -s proxy.example.com:7080 -o config.yaml
bifrost-client -c config.yaml

Test Route Resolution

bifrost-client ctl test google.com
# Output: google.com -> server (matched rule: default)