BLOMBoundary Layer Labs
Start free
Menu
All guides

Get started

The BLOM method

Your work

Agents

Design Lab

Developers

Administration

DocsDevelopers

The CLI

BLOM's command-line client comes from BLOM itself. Sign in through your browser, then work your queue, claims, and notes from a terminal or a script.

In BLOMOrganizationConnect Agent

Get the CLI

The CLI is one file, blom-cli.mjs, which runs with Node.js 22 or later. BLOM serves it from its own address, beside a manifest that names its version and its SHA-256.

  1. Download it

    In BLOM, open Organization, then Connect Agent, and under The BLOM CLI select blom-cli.mjs. Or fetch it from a terminal. The download needs no sign-in.

    curl -fsSLO https://blom.boundarylayerlabs.com/downloads/blom-cli.mjs

  2. Check it

    Before you run it, compare its SHA-256 with the sha256 its manifest names, ignoring case. The manifest is at https://blom.boundarylayerlabs.com/downloads/blom-cli.json, and Connect Agent shows the same value. Any of these prints the file's:

    sha256sum blom-cli.mjs                       # Linux
    shasum -a 256 blom-cli.mjs                   # macOS
    Get-FileHash blom-cli.mjs -Algorithm SHA256  # Windows PowerShell

  3. Run it

    node blom-cli.mjs help lists the commands, and node blom-cli.mjs help <command> shows one command's options. node blom-cli.mjs --version prints the CLI's version.

Note. The CLI's help and messages call it blom, as in blom login. This guide runs it as node blom-cli.mjs. A shell alias saves the typing.

Sign in

The CLI signs you in through BLOM in your browser, as you sign in to the BLOM app. It never asks for a password.

  1. Start the sign-in

    Run login with BLOM's address:

    node blom-cli.mjs login --url https://blom.boundarylayerlabs.com

    Your browser opens BLOM's Command-line sign-in page, and the CLI waits up to 5 minutes. Add --no-browser to print the address instead of opening it, or --org with an organization's id to choose it in advance.

  2. Allow it

    Choose the Organization the CLI works in, then select Allow. The page says the sign-in returns to this computer at 127.0.0.1 and a port. Allow it only if you just ran login yourself. Deny ends the sign-in.

  3. Check who you are

    The terminal says, for example, "Signed in to Harbor Labs at https://blom.boundarylayerlabs.com as Ada Lovelace." Run node blom-cli.mjs whoami to see your organization, your role, when the sign-in ends, and the operations you may call now.

The CLI keeps one sign-in for each BLOM address, in one organization. To work in another organization, run login again: the new sign-in replaces the old one, and the CLI ends the old one at BLOM.

The sign-in is kept in config.json, in a folder of your own: AppData\Roaming\blom in your Windows profile, ~/Library/Application Support/blom on macOS, and ~/.config/blom elsewhere. On macOS and Linux, only you can read it.

Who it acts as

Signed in
The CLI acts as you, in the organization you chose, through BLOM's public API. It can do what you can do in the BLOM app there, except credentials, roles, invitations, connections, and your own sign-in. Its changes are recorded as yours, made through the CLI.
With an agent key
Set BLOM_TOKEN to an agent's key and the CLI acts as that agent, ignoring any sign-in. Use this in scripts and CI. The agent may do what its key's access allows, and its changes are recorded under its name with its accountable owner beside it, such as Claude · Ada Lovelace.

BLOM checks every call as it checks the BLOM app's. What you, or the key, may do decides, never the CLI.

VariableWhat it sets
BLOM_URLBLOM's address, for a command without --url. With neither, the CLI uses the address you last signed in to. It must be an https address.
BLOM_TOKENAn agent's key. While it's set, every call uses it, and login and logout refuse to run.
BLOM_EXTRA_HEADEROne more header, written Name: value, sent with every request. It can't set Authorization, Cookie, Host, or BLOM-Client, and the CLI never prints it.

Caution. Keep an agent's key in the environment of the script that uses it, never in a repository, a task, or a document. Anyone holding it acts as that agent.

Commands

Each command that calls BLOM takes --url and --json. A <task> is a task's key, such as HL-12, or its id. A command that changes something also takes --request-id, below.

CommandWhat it does
loginSigns you in through BLOM in your browser.
logoutEnds this computer's sign-in at BLOM and removes it.
whoamiWho BLOM says you are, in which organization, with which role, and the operations you may call now.
queueYour queue: the next actions waiting on you, with their claims, and the notes that mention you. Filter with --product, --type, or --claim-state.
work-listTasks by --status open|closed|all, --product, --home, --type, --owner me, --initiative, or --kind job|report.
task captureCaptures a task, which you own, from --type, --home, and --title, with an optional --initiative, --parent Job, and --description or --description-file.
note add <task>Adds a note of at most 500 characters with --body. Repeat --mention to tell someone. --corrects adds a note that corrects an earlier one, since nothing edits a note.
review record <job>Records a review on a Job, with --verdict, --independence, and what you reviewed: --pull-request or --document with --pin, or --commit. A review is evidence, never an approval.
claim <task>Claims the task's next action. --mode resume resumes your own Stale claim, and --mode takeover takes over another's.
renew <task>Renews your Active claim, with a --note on progress.
complete <task>Completes the next action with one of its outcomes, by label or id, in --outcome. A Release step also names its --environment.
release <task>Releases your claim, with a --reason.
context export <task>Exports the task's context, as BLOM's records hold it. --out writes the answer to a file.
closure return <task>Returns a session's closure from a JSON --file, or - for standard input: what changed, what was checked, and what remains.
webhooks …list, create, pause, resume, delete, rotate-secret, test, and deliveries. In webhooks create, --url is the receiver's address. See Webhooks.
design post <path>Posts a design version to Design Lab: a folder, a .zip, or one .html file. See Post a design.
op <operation>Calls any operation you may call, by name, such as tasks.capture, with a JSON object from --input, a file or -.

A session with a task might run like this:

node blom-cli.mjs queue
    node blom-cli.mjs claim HL-12 --note "Starting the expiry check"
    node blom-cli.mjs renew HL-12 --note "Tests written; wiring the check next"
    node blom-cli.mjs note add HL-12 --body "Expiry now uses the invitation's own time zone."
    node blom-cli.mjs release HL-12 --reason "Waiting on the email template"

Output and exit codes

A command that succeeds prints a short summary. With --json it prints BLOM's answer exactly as it came. When a list has more, the summary ends with the --cursor to run it again with.

A refusal prints one line on standard error: BLOM's title, the status, code, and reason, the step to take, and BLOM's request id. With --json, it prints BLOM's problem details as they came.

Exit codeWhat it means
0Done.
1Failed: nothing with that id or key was found, BLOM failed after retries or couldn't be reached, or a sign-in didn't finish.
2The arguments or the input were wrong, or login or logout ran while BLOM_TOKEN was set.
3Not signed in, or BLOM refused the sign-in or the key. Sign in again, or check BLOM_TOKEN.
4Not permitted: you may not do this, or BLOM doesn't offer that operation to you.
5Conflict: the record changed since it was read, a gate isn't met, or a precondition failed.
6Rate limited. Wait the seconds the line names, then try again.

Retries and repeats

Each request gives up after 30 seconds, or 3 minutes for a Design Lab upload. When the connection fails, or BLOM answers with an error it marks safe to retry, the CLI tries twice more, after 1 and then 3 seconds. It waits out a rate limit once, when BLOM asks it to wait 10 seconds or less.

A change carries a request id, which its retries keep, so BLOM makes it once. To repeat a change safely when its answer is lost, give it your own --request-id, a UUID, and run the same command again with the same one. For 7 days, BLOM answers with the first result and changes nothing again.

Sign out

A sign-in lasts up to 30 days, and ends after 7 days unused. The CLI refreshes its access token, which lasts an hour, by itself.

  • From the terminal. node blom-cli.mjs logout ends this computer's sign-in at BLOM and removes it. If BLOM can't confirm that it ended, the CLI still removes it here and tells you to end it from your profile.
  • From BLOM. Open Your profile from your name in the rail, and find Command-line sign-ins. Each row shows the organization, when it Signed in, when it was Last used, when it Ends by, and the CLI's Version. Select Sign out on a row, or Sign out of all. The CLI's next call is refused.

An agent's key isn't a sign-in, so logout doesn't end it. Revoke it on API keys.

The public APIThe addresses, tokens, answers, and errors the CLI uses. Agent keysMake the key a script or CI sets as BLOM_TOKEN. WebhooksTell your own systems when work changes in BLOM. LimitsRate limits, sizes, and how long sign-ins last.
Can't find what you need?

Write to us, and we'll answer and add it here.

service@boundarylayerlabs.com