Command line interface

Use the bex command to manage a configured Bex platform from your terminal. It imports the Render CLI command implementation with Bex API/configuration defaults and adds Bex-specific commands. The upstream pin records the source version; installed releases can differ. Check bex -v and command help for your version, and see compatibility for server limits.

Set up the CLI​

Install Bex​

With Homebrew:

brew install bex-co/tap/bex
bex -v

Alternatively, the macOS/Linux installer verifies signed release checksums and installs to ~/.local/bin. It requires cosign on PATH:

curl -fsSL https://raw.githubusercontent.com/bex-co/bex/main/scripts/install-bex.sh | sh

Ensure the install directory is on PATH. BEX_VERSION pins an installer version; BEX_INSTALL_DIR changes its destination. For source builds and provenance details, see the upstream Bex CLI guide.

For the Bex Desktop app (macOS, Windows, Linux installers and release notes), see /download. Machine clients use the same stable feed at /releases/stable/latest and /api/release_notes/v2/stable/latest.

Sign in and select a workspace​

bex login
bex workspaces -o json
bex workspace set YOUR_WORKSPACE_ID
bex services -o json

Complete the browser authorization opened by bex login. The CLI stores its interactive credential in ~/.bex/cli.yaml and refreshes its short-lived access token. Use the returned workspace ID; selecting a workspace determines where subsequent commands operate, but does not grant additional permissions.

Run bex logout to revoke the stored interactive credential and remove the local configuration. It does not revoke or unset a separately supplied environment token.

Configure a self-hosted installation​

For example, with a local API already configured:

BEX_HOST=http://localhost:8090/v1/ bex login
BEX_HOST=http://localhost:8090/v1/ bex workspaces -o json

Set the host consistently for login and later commands. Explicit nonempty corresponding RENDER_* variables take precedence over Bex defaults and mappings. Remove unintended overrides if the CLI calls the wrong platform or uses an old credential. Some inherited help text still describes Render defaults; the table above describes the Bex bridge.

Common commands​

Use IDs returned by your installation in place of the examples. Run bex <command> --help for the exact arguments accepted by your binary. For every command, flag, and compatibility grade, see the CLI reference.

Deploy and inspect a service​

bex deploys list srv-abc123 -o json
bex deploys create srv-abc123 --wait
bex logs --resources srv-abc123 --type app --text timeout -o json
bex logs --resources srv-abc123 --tail

--wait waits for the deployment result and exits nonzero on a failed deploy. Check application behavior afterward: deployment readiness alone does not prove that a worker processed a job or a public hostname has a working certificate. See how deploys work and logs.

bex restart srv-abc123 restarts the service. bex ssh srv-abc123 opens a shell only when its service type, plan, gateway, SSH key, and your permissions allow it. A shell accesses the live workload and its secrets; it is not a read-only view.

Inspect datastores​

bex postgres list -o json
bex keyvalues list -o json
bex psql dpg-abc123 -c "SELECT NOW();" -o text
bex kv-cli red-abc123

Interactive connections require the corresponding local client and an allowed network path. Use returned connections and preserve their TLS requirements; Postgres and Key Value explain the resource-specific details. A database query can modify data even when invoked from an otherwise familiar CLI.

Scripts and CI​

A Bex API key is an OAuth client ID/secret pair. Its secret is not a bearer token. Create the key through an eligible human account, store the pair in the CI secret store, and exchange it for each job. This example requires curl and jq; set the workspace/service IDs and OAuth URL for your installation:

export BEX_HOST='https://api.bex.co/v1/'
export BEX_WORKSPACE='replace-with-workspace-id'
export BEX_OAUTH_TOKEN_URL='https://oauth.bex.co/oauth2/token'
 
BEX_ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error \
  "$BEX_OAUTH_TOKEN_URL" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$BEX_KEY_ID" \
  --data-urlencode "client_secret=$BEX_KEY_SECRET" \
  | jq -er '.access_token')
export BEX_ACCESS_TOKEN
 
bex deploys create "$BEX_SERVICE_ID" --wait -o json --confirm
unset BEX_ACCESS_TOKEN

Keep shell tracing off around credentials, fail the job if exchange fails, and never persist the token as an artifact. Renew according to token expiration; logout does not manage this environment credential. See API authentication.

Use explicit IDs and machine-readable output. --confirm skips CLI prompts; it is appropriate only after the job's intended action is authorized. It does not bypass server permissions or protected-environment rules.

Coding-agent launchers​

The same binary provides bex glm, bex kimi, bex deepseek, and bex muse. Each launches an installed claude executable against the corresponding model provider using your provider key. This is separate from deploying to Bex or connecting an agent through MCP.

bex glm
bex code keys
bex code keys set glm
bex code keys unset glm

A first launch can prompt for a key and validate it with the provider. Stored keys live in the owner-restricted ~/.bex/code/keys.toml; provider-specific environment variables take precedence. BEX_CODE_HOME relocates this directory. The key is passed to the child process, so these are sensitive local credentials.

Launchers use separate provider configuration directories and pass arguments after the provider name through to Claude Code, for example bex glm --continue. Register MCP connections in the configuration the launched session actually uses. See the launcher index and the GLM, Kimi, DeepSeek, and Muse guides for provider-specific setup.

Compatibility and differences​

An imported command appearing in --help does not establish that the Bex backend implements its workflow. In particular, do not assume Render Workflows, PR previews, ephemeral SSH instances, or hosted one-off jobs are supported. The CLI reference marks each command with its checklist grade so unsupported surfaces are never presented as working. Blueprint validation must check Bex capabilities, not merely generic Render YAML.

Bex uses its configured region and plans; Render account credentials, resource IDs, and infrastructure guarantees do not transfer. bex docs opens the Bex source guide. Imported client-side commands such as skills still have upstream behavior despite Bex help branding.

The upstream pin and compatibility checklist record the reviewed versions and limits. Test the commands your integration uses against your Bex version before upgrading.

Upgrade and troubleshoot​

Use bex upgrade --check to check availability. bex upgrade verifies and installs a release for a directly installed binary; Homebrew-managed installs receive a package-manager upgrade hint instead.

For a local operator deployment, start with the quickstart. For platform automation, use the API guide alongside this page.