CLI

bsfw is the Bytesafe Dependency Firewall CLI. It talks to the same management API as the dashboard: list firewalls, rules, and exceptions, query and stream logs, export and import configuration, and exchange OpenID Connect (OIDC) tokens in CI.

Environment variables

BYTESAFE_NAMESPACE and every --firewall <firewall-id> take IDs, not the display names you typed when creating them: the namespace ID from the URL path, the firewall ID from the firewall list or its Setup tab. Passing the display name does not resolve.

Global flags

The interaction ID is an opaque string of your choice, recorded on every log entry the request produces. Use it to tag requests with whatever dimension you want to correlate on later: a CI pipeline run (build-4711), an application or project (checkout-service), an environment (staging), or a combination (checkout-service/staging/build-4711). The firewall does not interpret the value; it only stores it for filtering and grouping in the logs. See Access Tokens for how the ID travels with the token.

List commands accept --format table|json. Default is table.

Commands

bsfw firewalls

List firewalls in the namespace. Read-only; create a firewall with config import.

bsfw firewalls
bsfw firewalls --format json

bsfw rules

List rules for a firewall. Read-only; create or change rules by editing the rules array via config import.

bsfw rules --firewall <firewall-id>

bsfw exceptions

List exceptions for a firewall. Read-only; create or change exceptions by editing the exceptions array via config import.

bsfw exceptions --firewall <firewall-id>

Same flags as rules.

bsfw logs

Query or stream firewall logs.

bsfw logs --firewall <firewall-id>
bsfw logs --firewall <firewall-id> --tail
bsfw logs --all-users

Without a user filter, you see your own entries.

bsfw config export

Export the full firewall configuration, including rules and exceptions, as JSON to stdout.

bsfw config export --firewall <firewall-id> > firewall-config.json

Exported configuration is the basis for config-as-code workflows: keep the JSON in git, edit, and import.

bsfw config import

Import a firewall configuration from JSON. This is an upsert of the full config, and the CLI's create and update path:

• Create a firewall. Import a config with a firewall ID that does not exist yet. Requires the fw:create permission. A practical starting point is exporting an existing firewall and changing the id.
• Create or change rules and exceptions. Export the config, edit the rules or exceptions arrays, and import it back.
• Credentials never travel through import. Exports contain placeholders, and imports reject plaintext credential values. A placeholder preserves an existing target's stored value; under a new firewall ID or upstream it resolves to empty. Set credentials separately with config credentials.

bsfw config import --file firewall-config.json
bsfw config import < firewall-config.json

The config JSON must contain the firewall id. A typical edit round trip:

bsfw config export --firewall <firewall-id> > firewall-config.json
# edit firewall-config.json: add a rule, add an exception, change upstreams
bsfw config import --file firewall-config.json

bsfw config credentials

Set credentials for an upstream. Credentials are not part of exports, so this is how you provide them after an import.

bsfw config credentials --firewall <firewall-id> --upstream <upstream-id>

bsfw oidc exchange

Exchange a GitHub Actions OpenID Connect (OIDC) ID token for a short-lived Service Access Token (sat-). Inside GitHub Actions with permissions: id-token: write, the ID token is fetched automatically for the configured Trusted Builder audience. The exchange endpoint is unauthenticated, so BYTESAFE_TOKEN is not required.

bsfw oidc exchange --audience bytesafe:trusted-builder:<id>

End-to-end setup, including Trusted Builder registration: GitHub Actions.

Related

• How-to: View logs
• Getting started: Access Tokens, GitHub Actions, Config as code
• Reference: API