@stoneforgelabs/forge-logger-cli

A headless, AI-agent-friendly CLI for Forge Logger. Everything in the web app's core loop — create a project, mint an ingest token, read reports — is driveable from the terminal or by an AI agent, with zero UI clicks.

It wraps the generated TypeScript SDK (src/_generated/api, regenerated from the backend's OpenAPI doc), so the CLI stays in lock-step with the API.

The command is forgelogger (short alias: flg).

Install

# Zero-install — ideal for AI agents and CI
npx @stoneforgelabs/forge-logger-cli init --name "My Game" --json

# Or install globally for interactive use
npm i -g @stoneforgelabs/forge-logger-cli
forgelogger --help

Requires Node.js 20+.

Local development (from the monorepo)

pnpm install
pnpm --filter @stoneforgelabs/forge-logger-cli build
node apps/forge-logger-cli/dist/index.js --help
# or without building:
pnpm --filter @stoneforgelabs/forge-logger-cli forge -- --help

Configuration

Config lives at ~/.forgelogger/config.json (override the dir with FORGE_CONFIG_DIR). The file is written with 0600 perms because it holds a session token.

Environment variables override the file, so agents / CI can run non-interactively:

| Var | Purpose | | --- | --- | | FORGE_API_URL | Management API base URL (default http://localhost:3001) | | FORGE_TOKEN | JWT access token (skips forgelogger login) | | FORGE_EMAIL / FORGE_PASSWORD / FORGE_NAME | Non-interactive login / register | | FORGE_INGEST_URL | Ingest API base URL (for future ingest commands) |

Commands

# Auth
forgelogger register --email [email protected] --password '••••' --name "My Studio"
forgelogger login    --email [email protected] --password '••••'
forgelogger whoami
forgelogger logout

# One-shot bootstrap: project + environment + ingest token (token printed once)
forgelogger init --name "My Game" --env Production
forgelogger init --name "My Game" --slug my-game --expires-in-days 90 --json

# Read side (accepts project id OR slug)
forgelogger projects list
forgelogger reports list my-game --severity critical --status new --limit 20
forgelogger reports get my-game <reportId>
forgelogger events list my-game --limit 50

# Export a report to a connected tracker (non-github providers need a paid plan)
forgelogger export my-game <reportId> --provider github

# Config
forgelogger config show
forgelogger config set baseUrl https://api.forgelogger.dev
forgelogger config path

Add --json to any command for machine-readable output (status/progress text goes to stderr, results to stdout — safe to pipe).

Agent quick-start

export FORGE_API_URL=https://api.forgelogger.dev
npx @stoneforgelabs/forge-logger-cli register --email "$EMAIL" --password "$PW" --json   # or login
npx @stoneforgelabs/forge-logger-cli init --name "My Game" --json                       # capture .token.value

Regenerating the SDK

The SDK is seeded from the frontend's generated client. To refresh it against a running backend (port 3001):

pnpm --filter @stoneforgelabs/forge-logger-cli api:generate

Releasing

Publishing is driven by a git tag (see .github/workflows/cli-release.yml):

# bump the version in package.json first, commit it, then:
git tag cli-v0.1.0
git push origin cli-v0.1.0

The workflow builds and runs pnpm publish (which resolves catalog: versions), so always publish via pnpm — npm publish would emit invalid catalog: specs.

Known limitation

The management API is JWT-only; there is currently no long-lived machine credential for read/management endpoints (the flg_ ingest token is write-only). For interactive/dev use forgelogger login stores a 7-day JWT. For durable CI/agent access, a read-scoped personal access token on the backend is the planned follow-up (wiring the existing CombinedAuthGuard onto the read routes).