RetroBot CLI

RetroBot CLI lets participants submit retrospective feedback from a terminal with the participant link shared by their Scrum Master. The npm package is @retrobot/cli and the executable is rb.

Node.js 20 or later is required.

Install

After publication:

npm install -g @retrobot/cli

During local development:

npm ci
npm run build
npm link
rb help

Configure

Configure the CLI with a RetroBot participant link:

rb configure https://www.retro-bot.com/p/<participant-token>

The CLI stores the API base URL and participant token in the user config directory for the operating system. It talks only to the public participant-link HTTP API and does not import RetroBot backend code.

Raw tokens are accepted only when an API base URL is provided:

rb configure <participant-token> --api-base https://www.retro-bot.com/api/v1

Submit

Submissions are anonymous by default:

rb submit "The release handoff was clearer this sprint." --accept-terms <terms-version>

Named feedback uses an explicit display name:

rb submit "Pairing helped unblock testing." --name Avery --accept-terms <terms-version>

Piped workflows use standard input:

echo "The standup board needs grooming." | rb submit --stdin --accept-terms <terms-version>

On success, the CLI prints only:

submitted

It never prints the feedback body after sending, participant token, full participant link, or submission ID.

Legal Acknowledgement

Before submitting feedback, participants must acknowledge the current RetroBot legal versions returned by the participant-link API.

Interactive terminals prompt once per parent shell session and prompt again if the terms version changes. Non-interactive contexts, including pipes and CI, must pass:

rb submit --stdin --accept-terms <current-terms-version>

Use rb status to see the configured workspace, feedback state, and current terms version without printing the participant token.

Token Privacy

The participant link is the CLI credential. Treat it like a secret.

• Never commit real participant links or tokens.
• Use placeholders in examples, tests, logs, and support snippets.
• Ask the Scrum Master for a fresh link if the workspace participant link has been regenerated.
• Set RETROBOT_CONFIG_DIR to isolate local or smoke-test configuration.

Smoke Testing

Run the full local release check:

npm run release:check

That command runs lint, typecheck, tests, build-through-pack, and npm pack --dry-run.

Windows PowerShell

Run a package/install smoke without a live participant link:

.\scripts\smoke.ps1

Run an optional live smoke with a staging or test participant link:

$env:RETROBOT_SMOKE_PARTICIPANT_LINK = "https://www.retro-bot.com/p/<test-token>"
.\scripts\smoke.ps1

If feedback is open, the script reads the current terms version from rb status and submits one smoke feedback item. If feedback is not open, it stops after configure/status.

Bash/Zsh

Run the package/install smoke in a temporary npm prefix:

npm ci
npm run release:check
tarball="$(npm pack --silent | tail -n 1)"
prefix="$(mktemp -d)"
config_dir="$(mktemp -d)"
npm install -g --prefix "$prefix" "./$tarball"
export PATH="$prefix/bin:$PATH"
export RETROBOT_CONFIG_DIR="$config_dir"
rb version
rb help
rb status || test "$?" -eq 2
rm -f "$tarball"

rb status should exit with code 2 before configuration and print the not-configured message.

Optional live smoke with a staging or test participant link:

rb configure "https://www.retro-bot.com/p/<test-token>"
rb status
terms_version="$(rb status | awk -F': ' '/^Terms:/ { print $2 }')"
rb submit "CLI smoke submission from bash or zsh" --accept-terms "$terms_version"

Use only staging or test links for smoke tests. Do not paste real participant tokens into committed files.

Development

npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

Available package scripts:

• npm run lint checks source and tests with ESLint.
• npm run typecheck runs TypeScript without emitting files.
• npm test runs Vitest.
• npm run build emits the CLI package to dist/.
• npm run pack:dry-run runs npm pack --dry-run.
• npm run release:check runs the release validation gate.
• npm run dev runs the TypeScript entrypoint locally.

Troubleshooting

RetroBot is not configured. Run: rb configure <participant-link>
Run rb configure with the participant link shared by your Scrum Master. Exit code: 2.

This participant link is no longer valid...
The link may be incorrect or regenerated. Ask your Scrum Master for the latest link and run rb configure <link>. Exit code: 3.

Feedback is not open right now...
The workspace has no active retro accepting feedback. Try again when the Scrum Master opens feedback. Exit code: 4.

Feedback must be 5000 characters or fewer.
Shorten the feedback and submit again. Exit code: 5.

Too many submissions. Please try again later.
The public submission throttle was reached. Wait before trying again. Exit code: 6.

RetroBot could not be reached...
Check network connectivity, the API base URL, and service availability. Exit code: 7.

Terms acknowledgement is required...
Run rb status to read the current terms version, then re-run submit with --accept-terms <version>. Exit code: 8.

RetroBot configuration is invalid...
Re-run rb configure <participant-link>. For smoke tests, set a fresh RETROBOT_CONFIG_DIR to isolate the config file.

Release

This package is configured for public scoped npm publishing with the next tag, but publishing is a separate operator action. Do not publish until npm scope ownership, license posture, tarball contents, and Windows PowerShell, bash, zsh, and VS Code terminal smokes are confirmed.

Release validation command:

npm run release:check