Using the CLI

The bgagent CLI is the recommended way to interact with the platform. It authenticates via Cognito, manages token caching, and provides formatted output.

This repository builds the CLI under cli/; after compile, run the entrypoint as node lib/bin/bgagent.js from the cli directory (the path package.json exposes as bin). If you install a published package or link bgagent onto your PATH, you can call bgagent directly - the subcommands are the same.

Setup

cd cli
mise run build

# Configure with your stack outputs (run from cli/)
node lib/bin/bgagent.js configure \
  --api-url $API_URL \
  --region "$REGION" \
  --user-pool-id $USER_POOL_ID \
  --client-id $APP_CLIENT_ID

# Log in
node lib/bin/bgagent.js login --username user@example.com

Submitting a task

# From cli/  - from a GitHub issue
node lib/bin/bgagent.js submit --repo owner/repo --issue 42

# From a text description
node lib/bin/bgagent.js submit --repo owner/repo --task "Add input validation to the /users POST endpoint"

# Iterate on an existing pull request (address review feedback)
node lib/bin/bgagent.js submit --repo owner/repo --pr 42

# Iterate on a PR with additional instructions
node lib/bin/bgagent.js submit --repo owner/repo --pr 42 --task "Focus on the null check Alice flagged"

# Review an existing pull request (read-only  - posts structured review comments)
node lib/bin/bgagent.js submit --repo owner/repo --review-pr 55

# Review a PR with a specific focus area
node lib/bin/bgagent.js submit --repo owner/repo --review-pr 55 --task "Focus on security and error handling"

# Submit and wait for completion
node lib/bin/bgagent.js submit --repo owner/repo --issue 42 --wait

Example (default text output immediately after a successful submit - task is SUBMITTED, branch name reserved):

node lib/bin/bgagent.js submit --repo krokoko/agent-plugins --task "add codeowners field to RFC issue template"

Task:        01KN37PZ77P1W19D71DTZ15X6X
Status:      SUBMITTED
Repo:        krokoko/agent-plugins
Description: add codeowners field to RFC issue template
Branch:      bgagent/01KN37PZ77P1W19D71DTZ15X6X/add-codeowners-field-to-rfc-issue-template
Created:     2026-04-01T00:39:51.271Z

Options:

Flag	Description
--repo	GitHub repository (owner/repo). Required.
--issue	GitHub issue number.
--task	Task description text.
--pr	PR number to iterate on. Sets task type to pr_iteration. The agent checks out the PR’s branch, reads review feedback, and pushes updates.
--review-pr	PR number to review. Sets task type to pr_review. The agent checks out the PR’s branch, analyzes changes read-only, and posts structured review comments.
--max-turns	Maximum agent turns (1–500). Overrides per-repo Blueprint default. Platform default: 100.
--max-budget	Maximum cost budget in USD (0.01–100). Overrides per-repo Blueprint default. No default limit.
--idempotency-key	Idempotency key for deduplication.
--trace	Enable detailed tracing: raises progress preview cap to 4 KB and uploads full NDJSON trajectory to S3 on completion. Download with bgagent trace download.
--wait	Poll until the task reaches a terminal status.
--output	Output format: text (default) or json.

At least one of --issue, --task, --pr, or --review-pr is required. The --pr and --review-pr flags are mutually exclusive.

Checking task status

Run these from the cli/ directory (same as in Setup).

Single task

node lib/bin/bgagent.js status <TASK_ID>

# Poll until completion
node lib/bin/bgagent.js status <TASK_ID> --wait

Example (default text output once the task has finished - COMPLETED, with session id, PR link, duration, and cost):

node lib/bin/bgagent.js status 01KN37PZ77P1W19D71DTZ15X6X

Task:        01KN37PZ77P1W19D71DTZ15X6X
Status:      COMPLETED
Repo:        krokoko/agent-plugins
Description: add codeowners field to RFC issue template
Branch:      bgagent/01KN37PZ77P1W19D71DTZ15X6X/add-codeowners-field-to-rfc-issue-template
Session:     9891af91-bfc6-488f-bfe6-ce8f8c9a63cf
PR:          https://github.com/krokoko/agent-plugins/pull/60
Created:     2026-04-01T00:39:51.271Z
Started:     2026-04-01T00:39:56.647Z
Completed:   2026-04-01T00:43:49Z
Duration:    148.6s
Cost:        $0.1751

All tasks

node lib/bin/bgagent.js list
node lib/bin/bgagent.js list --status RUNNING,SUBMITTED
node lib/bin/bgagent.js list --repo owner/repo --limit 10

Viewing task events

node lib/bin/bgagent.js events <TASK_ID>
node lib/bin/bgagent.js events <TASK_ID> --limit 20
node lib/bin/bgagent.js events <TASK_ID> --output json

Use --output json to see the full payload for preflight_failed (reason, detail, and per-check metadata). See Task events under Task lifecycle for how to interpret common reason values.

Watching a task in real time

Stream progress events (turns, tool calls, tool results, milestones, cost updates) from a running task and exit automatically when it reaches a terminal state.

node lib/bin/bgagent.js watch <TASK_ID>

# JSON output (one event per line) — useful for scripting
node lib/bin/bgagent.js watch <TASK_ID> --output json

Exit codes: 0 on COMPLETED, 1 on FAILED / CANCELLED / TIMED_OUT. Press Ctrl+C to exit early without affecting the task.

Steering a running task (nudge)

Send a mid-run message to the agent while it is working. The agent emits a nudge_acknowledged milestone before incorporating your guidance into its next turn.

node lib/bin/bgagent.js nudge <TASK_ID> "Focus on the auth module first"

# Example: redirect scope mid-task
node lib/bin/bgagent.js nudge <TASK_ID> "Skip the docs update, just fix the handler"

Nudges are delivered between turns — the agent finishes its current tool call before reading the message. You can send multiple nudges; each one is acknowledged in order.

Tracing a task

Submit a task with --trace to enable detailed tracing. This raises the progress-writer preview cap from 200 chars to 4 KB and uploads a full gzipped NDJSON trajectory to S3 when the task finishes.

# Submit with tracing enabled
node lib/bin/bgagent.js submit --repo owner/repo --issue 42 --trace

# Download the trace after the task completes
node lib/bin/bgagent.js trace download <TASK_ID>

# Pipe to jq for analysis
node lib/bin/bgagent.js trace download <TASK_ID> | gunzip | jq -s .

# Save raw gzip to a file
node lib/bin/bgagent.js trace download <TASK_ID> -o trace.ndjson.gz

# Overwrite existing file
node lib/bin/bgagent.js trace download <TASK_ID> -o trace.ndjson.gz --force

Debug output

Add --verbose to any bgagent command to emit the full HTTP request/response cycle on stderr. This is useful for diagnosing auth, network, or API contract issues.

node lib/bin/bgagent.js --verbose status <TASK_ID>
node lib/bin/bgagent.js --verbose submit --repo owner/repo --task "Fix the bug"

Cancelling a task

node lib/bin/bgagent.js cancel <TASK_ID>