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

Operator commands (stack admin)

Stack admins can introspect deployment state and run smoke checks without Cognito login — these commands use operator AWS credentials (IAM profile / AWS_REGION):

# Print stack outputs (ApiUrl, UserPoolId, AppClientId, GitHubTokenSecretArn, …)
bgagent platform outputs --stack-name backgroundagent-dev

# Smoke-check API, Cognito, GitHub token, Bedrock model, onboarded repos
bgagent platform doctor --stack-name backgroundagent-dev

# List onboarded repositories
bgagent repo list

# Show RepoConfig for one repo (secret ARNs redacted)
bgagent repo show owner/repo

# Store the platform GitHub PAT (or a per-blueprint secret via --repo)
bgagent github set-token
bgagent github set-token --repo owner/repo

The read-only operator commands (platform, repo, runtime, ops, webhook test, admin list-users) accept --output json; the credential-writing github and admin invite-user/delete-user/reset-password commands do not. Region defaults to bgagent configure --region or AWS_REGION.

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"

# Select an explicit workflow (overrides the one --pr/--review-pr would imply)
node lib/bin/bgagent.js submit --repo owner/repo --task "Research the tradeoffs" --workflow knowledge/web-research-v1

# Submit with attachments (local files)
node lib/bin/bgagent.js submit --repo owner/repo --task "Fix this bug" \
  --attachment screenshot.png \
  --attachment error.log

# Submit with a URL attachment
node lib/bin/bgagent.js submit --repo owner/repo --task "Implement this design" \
  --attachment https://figma.com/file/abc123/export.png

# 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 awslabs/agent-plugins --task "add codeowners field to RFC issue template"

Task:        01KN37PZ77P1W19D71DTZ15X6X
Status:      SUBMITTED
Repo:        awslabs/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. Selects the coding/pr-iteration-v1 workflow. The agent checks out the PR’s branch, reads review feedback, and pushes updates.
--review-pr	PR number to review. Selects the coding/pr-review-v1 workflow. The agent checks out the PR’s branch, analyzes changes read-only, and posts structured review comments.
--workflow	Workflow to run, as <id>[@<constraint>] (e.g. coding/new-task-v1). Overrides the workflow implied by --pr/--review-pr; omit to let the server resolve a default.
--attachment	Attach a file or URL (repeatable). Local files ≤ 500 KB are sent inline; larger files use presigned upload. URLs are fetched during hydration. See Attachments below.
--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.
--approval-timeout	Cedar HITL per-task approval timeout in seconds (default 300). A matching rule with its own @approval_timeout_s annotation still takes the minimum. See Approval gates.
--pre-approve	Cedar HITL scope to approve up-front (repeatable). Same scope forms as bgagent approve --scope. Hard-deny rules are always enforced.
--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.

Attachments

Attachments let you provide non-text context to the agent — screenshots of bugs, design mockups, CSV data, log files, or URLs to external resources. Every attachment passes through security screening before reaching the agent.

Supported file types:

Category	Types	Extensions
Images	PNG, JPEG	.png, .jpg
Text files	Plain text, CSV, Markdown, JSON, PDF, Log	.txt, .csv, .md, .json, .pdf, .log

Limits:

Limit	Value
Max attachments per task	10
Max size per attachment	10 MB
Max total size per task	50 MB
URL attachments	HTTPS only

Usage:

# Local file (auto-detects MIME type from content)
node lib/bin/bgagent.js submit --repo owner/repo --task "Fix this layout" \
  --attachment screenshot.png

# Multiple attachments
node lib/bin/bgagent.js submit --repo owner/repo --task "Analyze these logs" \
  --attachment error.log \
  --attachment metrics.csv

# URL attachment (fetched during task hydration)
node lib/bin/bgagent.js submit --repo owner/repo --task "Implement this design" \
  --attachment https://example.com/mockup.png

The CLI automatically routes attachments through the optimal upload path:

• Files ≤ 500 KB are sent inline (base64-encoded in the request body).
• Files > 500 KB use presigned upload (uploaded directly to S3, then confirmed).
• URLs are validated at submission and fetched during context hydration with SSRF protection.

Security screening:

All attachments are screened before reaching the agent:

• Images: Magic bytes validation, dimension checks (max 8000px per side), Bedrock Guardrail content screening (prompt attack detection). Only PNG and JPEG are accepted.
• Text files: Magic bytes validation, Bedrock Guardrail text content screening. PDFs have text extracted (max 50 pages) before screening.
• URLs: HTTPS-only enforcement, DNS resolution pinning (prevents DNS rebinding/SSRF), private IP blocking, redirect validation, size and timeout limits.

If any attachment fails screening, the entire task is rejected with a clear error identifying the problematic file. Re-submit without the flagged attachment.

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:        awslabs/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/awslabs/agent-plugins/pull/43
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>