BitLabs CLI

Go live with BitLabs — end to end from the CLI

This walkthrough takes you from zero to a live integration: grab a key, create an app, configure it, choose your demand formats, set and test callbacks, and verify you're live. Every step works for a human in a terminal or an AI agent (add --agent for JSON-only, non-interactive output).

The CLI wraps the documented BitLabs APIs — it never replaces the canonical docs at https://developer.bitlabs.ai. Where a step is dashboard-only today, this guide says so.

0. Install

go build -o ./bitlabs ./cmd/bitlabs
install -m 0755 ./bitlabs "$HOME/.local/bin/bitlabs"
bitlabs --version

1. Get access, then bootstrap

BitLabs is invite-only — apply on the website first. Once invited, create your Management API key under Dashboard → Company → API Keys: the creation dialog shows the key once, together with your Workspace ID — copy both. (App Tokens can also be grabbed manually per app under Dashboard → Apps → the app → Integration.)

bitlabs login

BitLabs has no browser sign-in: login collects the two dashboard values the CLI needs to call the Management API — it opens the key page (skip with --no-browser), asks for your Workspace ID, then your Workspace API Key with input hidden, verifies them (one read-only list-apps call), and stores them in the OS keyring (plain 0600 config file when no keyring is available). bitlabs whoami shows what is in use; bitlabs logout clears it. Non-interactive (CI, agents): printf '%s' "$KEY" | bitlabs login --workspace-id <id> --with-token, or set BITLABS_API_KEY and BITLABS_WORKSPACE_ID as environment variables — they take precedence over stored credentials.

One secret (the Workspace API Key) plus one identifier (the Workspace ID):

bitlabs setup bootstrap --json

Bootstrap lists the workspace's apps (the list carries no names, so matching reads each app's config), reuses the app named by --app-name (default "BitLabs Agent App") or creates it, and caches any credentials the app configuration exposes. The documented configuration identifiers do not include the App/S2S tokens, so bootstrap may report ready: false with next_steps — follow them: copy the App Token from Dashboard → Apps → the app → Integration (bitlabs auth set-token <token>), and the S2S token from the app's server-to-server section. A 403 on create means the workspace app limit is reached.

2. App provisioning

App selection/creation is part of bitlabs setup bootstrap. The selected App UUID and provisioned credentials are stored locally, so subsequent commands can use the correct API tier without additional credential prompts.

3. Decide four things (an agent asks; a human just picks)

Decide these before configuring — never default silently. An agent asks each one with exactly the options listed and no other option:

Question Options
Which demand formats? Offers, Surveys — either or both
Which integration? iframe (web offerwall in a page), User-based API (direct REST, you render the UI), Mobile SDK — and for Mobile SDK: Android, iOS, or Flutter
Currency name? suggestions: Coins, Points, Gems, Credits — or any name you like
Currency factor? how many units equal 1 USD — suggestions: 100, 1000, 10 — or any positive whole number

4. Configure the app

One command applies those answers with the documented Management API identifiers (app.features.offers.enabled, app.features.surveys.enabled, general.currency.symbol.content, general.currency.factor, app.behaviour.default_tab), sent as the top-level {internalIdentifier, value} array the config PATCH requires, and reads them back:

bitlabs setup configure-app --demand offers,surveys --currency-name Coins --currency-factor 100
bitlabs management-apps get --workspace-uuid <WORKSPACE_UUID> --app-uuid <APP_UUID>   # full config

Formats you do not list are disabled. Add --dry-run to preview the request. For any other configuration field, management-apps update-config --body-json '[{"internalIdentifier":"…","value":…}]' sends the same array shape; a 403 means the identifier is not allowed. bitlabs apps settings shows the resolved client-side view with the App Token.

5. Build the integration — always with your user id

Every call carries your id for the end user (≤255 characters, none of % $ * & #). BitLabs returns the same id as uid in the reward callback, which is how you credit the right account.

iframe / web offerwall

bitlabs iframe validate-params --uid <USER_ID>
bitlabs iframe generate-html --uid <USER_ID> --token <APP_TOKEN> --width 100% --height 600
bitlabs iframe runtime-messages --theme DARK      # origin-locked postMessage for live theming

User-based API — you render the UI; the API tracks state and never credits:

bitlabs offers list --user-id <USER_ID>            # open click_url (continue_url if already started); offers history for progress
bitlabs surveys list --user-id <USER_ID>           # ranked surveys with click_url; get-click / update-click / users history for state

On mobile, store the advertising id first (offers store-advertising-id) for targeting.

Mobile SDK — the SDKs host the same offerwall in a WebView:

bitlabs webview snippet --platform android    # or ios, flutter
bitlabs webview checklist

5b. When the integration is finished: wire the S2S reward callbacks

Rewards credit only via S2S callbacks, so once the integration works, wire them into your current system. The callback URL is app configuration (identifier app.features.callbacks.callback_default) stored as a templated URL: mandatory params uid/val/usd/tx (dedupe by tx — BitLabs retries up to 10×) plus recommended app_token/user_ip/ref. &hash= is appended by BitLabs at fire time — never store it in the template. The CLI builds and stores it correctly:

bitlabs callbacks set-url --url https://your-server.example/bitlabs/callback
bitlabs callbacks get-url                      # read back what's configured

Then generate the receiving handler for your framework and verify it:

bitlabs callbacks endpoint-template --framework express     # or fastify, next, generic — hash-verify + tx-dedupe handler
bitlabs callbacks verify-hash --url "<url-without-hash>" --hash <h>   # uses BITLABS_APP_SECRET
bitlabs callbacks-api test-url --url "https://your-server.example/bitlabs/callback"   # S2S token
bitlabs callbacks test-checklist

A callback isn't done until: a valid signed callback credits exactly once, a replayed tx does not credit twice, and a tampered hash is rejected. Note: browser redirect URLs (redirect_complete/screenout/click_termination) are a separate, optional survey-UX concept — they steer the user's browser, they do not credit rewards.

6. Go live

bitlabs auth status                             # all three tiers resolvable
bitlabs apps settings                           # app serves the expected config
bitlabs surveys list --user-id smoke-test-1     # live demand flows
bitlabs reports app-revenue --help              # revenue reporting, once traffic flows

When those pass, point production traffic at your integration. bitlabs doctor gives a one-shot health readout any time; bitlabs agent-context prints a machine-readable summary of the whole CLI for agent runners.

Where to go next