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
npx projen build

# Configure with your stack outputs (run from cli/)
node lib/bin/bgagent.js configure \
  --api-url $API_URL \
  --region us-east-1 \
  --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"

# 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.
--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.
--wait	Poll until the task reaches a terminal status.
--output	Output format: text (default) or json.

At least one of --issue or --task is required.

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

Cancelling a task

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