Automation

The CLI is built to be driven by something other than a person. Two rules make that work.

Output

Standard output is one JSON object and nothing else. Prose, progress and warnings go to standard error, so a caller reading stdout gets only the result.

--json turns itself on whenever stdout is not a terminal, so a piped or scripted call gets machine-readable output without asking for it. Force it either way with --json or --no-json.

Exit codes

The exit code says what happened, so nothing has to read the message.

Code	Meaning
0	Done
1	The command was wrong
2	Not signed in, or the credential was revoked
3	You may not do that
4	No such thing
5	The input was refused: bad repository, branch, path, or field
6	The app exists, and a step after it was refused
7	The instance could not be reached

Exit 6 is the one to handle. register adds the app and then its variables, targets and shares. A failure partway through leaves an app that exists with one thing missing. The message names the step that was refused. Fix that step and apply it on its own with env set, target add, or share. Running register again adds a second app.

Signing in without a browser

Create a token under Settings → Personal access tokens, then either sign in once:

sbd login --token -

Or skip signing in entirely and pass the token per run. STACKBOARD_TOKEN replaces the stored credential, so nothing is written to disk:

STACKBOARD_TOKEN=… STACKBOARD_HOST=https://stackboard.acme.com \
  sbd register --repo https://github.com/acme/dashboard --name "Sales dashboard"

That is how CI and the MCP server run.

Secrets

Danger

Never put a secret in an argument. A command line is visible in the process list, in shell history, and in the transcript of whichever agent typed it.

Pass the value through the environment and name the variable instead:

GIPHY_KEY=… sbd env set app1a2b3c4d --key GIPHY_KEY --secret-from GIPHY_KEY

The CLI enforces this rather than trusting it. A literal secret value is refused outright while --json is on, which is to say while a machine is driving it, and warns otherwise.

Refreshing cached data

A target with a cache keeps its responses until they expire. When the data upstream changes on a known schedule, clear the cache after it does, so the next load fetches fresh instead of waiting out the expiry:

# Every day at 06:15, after the nightly load
15 6 * * * STACKBOARD_TOKEN=… sbd cache clear app1a2b3c4d --target warehouse

The token must belong to one of the app’s owners. See cache clear.

Teaching a coding agent

The package ships a skill file describing what an agent needs to get right: that signing in is a person’s job, that a secret never goes in an argument, that every host the page calls needs a target, and what exit 6 means.

Drop it into a project:

mkdir -p .claude/skills/stackboard
cp "$(npm root -g)/@stackboard/cli/dist/skill/SKILL.md" .claude/skills/stackboard/

.agents/skills/stackboard/SKILL.md works the same way for agents that read that path.