@build-on-record/cli

CLI for Build on Record - log your build progress from the command line.

Installation

npm install -g @build-on-record/cli

Quick Start

1. Login to your Build on Record account:

   bor login

2. Set a project to log to:

   bor project set <project-slug>

3. Log your progress:

   bor "Implemented user authentication"

Commands

Authentication

bor login              # Login with email/password
bor logout             # Logout and clear credentials
bor whoami             # Show current user

Projects

bor project list       # List your projects
bor project set <slug> # Set default project for logging
bor project show       # Show current default project

Logging

bor log                     # Interactive log entry
bor log -t "Title" -c "Content"  # Quick log with title and content
bor "Quick message"         # Shorthand for quick logging

bor log also accepts --recorded-at <date> to backdate a record (ISO date, or a relative-ago offset like 2d, 1w), plus --type, --rationale, --expected-impact, --confidence, --review-at, and --outcome.

Records

bor records                 # List records in the project
bor record <recordId>       # Show a single record
bor update <recordId> --outcome "Shipped; +12% conversion" --confidence high

bor update only changes the fields you pass (true PATCH semantics) - it is the way to fill in an outcome after a decision plays out.

Configuration

bor config show        # Show current configuration
bor config url         # Show/set API URL
bor config reset       # Reset to defaults

API URL Configuration

By default, the CLI connects to the production API. You can configure a different URL:

# Use production (default)
bor config url production

# Use staging
bor config url staging

# Use custom URL
bor config url https://your-api.example.com

Automation, CI, and agents

The CLI is designed to run non-interactively so scripts, CI jobs, and coding agents can push and maintain records without a login prompt.

Authenticate with an environment variable

Generate an API token in the web UI (Settings → "CLI Access"), then expose it as an environment variable instead of running bor login:

export BOR_TOKEN="bor_xxxxxxxxxxxx"   # required
export BOR_PROJECT="my-project-slug"  # default project for record commands
export BOR_API_URL="https://api.buildonrecord.com"  # optional, override target

When BOR_TOKEN is set it takes precedence over any stored login, and the on-disk default project/URL are ignored (so an agent's token is never paired with whatever project you last selected interactively).

Machine-readable output

Pass the global --json flag to any command. In JSON mode:

• stdout carries only the success payload (parse this).
• stderr carries spinners, status, and errors (a { "error": "...", "code": "..." } envelope on failure).
• The exit code is 0 on success, non-zero on failure.

Missing required input (e.g. a title) becomes a structured error instead of an interactive prompt whenever BOR_TOKEN or --json is set, or there is no TTY.

End-to-end example

# Create a record and capture its id
id=$(bor log --json \
  --project my-project \
  --type decision \
  --title "Adopt feature flags" \
  --rationale "Decouple deploy from release" \
  --confidence medium | jq -r .id)

# ...later, once you know how it went, fill in the outcome
bor update "$id" --project my-project \
  --outcome "Rolled out to 100%, zero incidents" --confidence high --json

Snippet for another project's CLAUDE.md

## Build on Record

Log significant decisions, experiments, and outcomes to Build on Record using the
`bor` CLI (authenticated via the `BOR_TOKEN` env var; default project in
`BOR_PROJECT`):

- Record a decision: `bor log --json --type decision --title "..." --rationale "..."`
- Capture the printed `id`, and once the result is known, update it:
  `bor update <id> --outcome "..." --confidence high --json`
- List recent records: `bor records --json`

Always pass `--json` and read the record `id` from stdout.

Requirements

• Node.js 18 or higher
• A Build on Record account

Links

• Website
• GitHub
• Report Issues

License

MIT