Binboi Docs/Core/CLI Reference

CLI Reference

Every command the binboi binary accepts. All commands except login and version require a cached token. Run login once and the token is written to ~/.binboi/config.json.

Commands

Authenticate the CLI and cache the token.

code

binboi login --token <token>

Flags:

| Flag | Purpose | |---|---| | --token <token> | Personal access token in the form binboi_pat_<8 hex>_<36 hex> (56 chars total). | | --server <host:port> | Override the relay address. Defaults to api.binboi.com:8081. |

Example:

code

binboi login --token binboi_pat_a1b2c3d4_0123456789abcdef0123456789abcdef0123

Output:

code

Logged in as you@example.com (plan: FREE)
Token saved to ~/.binboi/config.json

`logout`

Clear the cached token from the config file.

code

binboi logout

`whoami`

Print the account associated with the cached token. Accepts only --token (or -token) — no -v, --verbose, or --debug flags.

code

binboi whoami

Output:

code

you@example.com — plan FREE — 1/2 active tokens

`http`

Open an HTTP tunnel from a local port to https://<subdomain>.binboi.com.

code

binboi http <port> [subdomain]

<port> is the local TCP port. [subdomain] is optional — Free accounts get a random subdomain per session; Pro and Max can pass a reserved one.

Example:

code

binboi http 3000

On startup the CLI replaces its output with a live, ngrok-style dashboard:

Tunnel URL (https://<sub>.binboi.com → localhost:<port>)
Relay address and ping latency
Uptime counter
Request and error counters, downstream / upstream bytes
p50 / p90 latency
A recent-requests table (method, path, status, RTT, time)

Press Ctrl+C to stop.

`start`

Alias for http. Same arguments.

code

binboi start 3000 my-app

`tunnels`

List active tunnels on your account.

code

binboi tunnels

Output:

code

SUBDOMAIN              PORT   STARTED
wispy-otter-7421       3000   2m ago
my-app                 8080   1h ago

`open`

Open a tunnel URL in your default browser.

code

binboi open [subdomain]

If [subdomain] is omitted, the most recently started tunnel is opened.

`requests`

Print recent requests captured for a tunnel.

code

binboi requests [subdomain]

Output:

code

METHOD  PATH         STATUS  DURATION  TIME
GET     /health      200     12ms      14:02:11
POST    /api/login   401     43ms      14:02:09

For full request bodies and headers, see binboi.com/dashboard/requests.

`version`

Print the CLI version.

code

binboi version

Environment variables

| Variable | Purpose | When to use | |---|---|---| | BINBOI_API_URL | Override the API base URL. Defaults to https://api.binboi.com. | Pointing the CLI at a staging API or a self-run mirror. | | BINBOI_SERVER_ADDR | Override the relay address. Defaults to api.binboi.com:8081. | Same as --server flag, but for non-interactive shells. | | BINBOI_AUTH_TOKEN | Inject the token without running login. | CI jobs, containers, ephemeral environments where writing to ~/.binboi/config.json is undesirable. | | BINBOI_TOKEN | Same as BINBOI_AUTH_TOKEN, lower precedence. | Legacy / fallback. |

Resolution order

Tokens:

--token flag (explicit)
BINBOI_AUTH_TOKEN env var
BINBOI_TOKEN env var
~/.binboi/config.json

Relay and API URLs:

--server / --api flags
BINBOI_SERVER_ADDR / BINBOI_API_URL env vars
~/.binboi/config.json
Built-in defaults (api.binboi.com:8081, https://api.binboi.com)

A stale env var set in your shell will silently override the config file — see Troubleshooting if login succeeds but whoami immediately fails.

Configuration file

The CLI persists state in ~/.binboi/config.json. It is written on login and read by every other command.

Shape:

code

{
  "token": "binboi_pat_...",
  "server_addr": "api.binboi.com:8081",
  "api_url": "https://api.binboi.com"
}

| Field | Source | |---|---| | token | The value passed to --token on login. | | server_addr | Relay address. Defaults to api.binboi.com:8081. | | api_url | API base URL. Defaults to https://api.binboi.com. |

To reset, run binboi logout or delete the file:

code

rm ~/.binboi/config.json

HTTP tunnels — how routing, retention, and quotas work.
API reference — REST endpoints behind the CLI.
Troubleshooting — common errors and fixes.