CLI Reference

forge init [name] [flags]

# Interactive mode (default)
forge init my-agent

# Non-interactive with all options
forge init my-agent \
  --framework langchain \
  --language python \
  --model-provider openai \
  --channels slack,telegram \
  --non-interactive

# From a skills file
forge init my-agent --from-skills SKILL.md

# From a skill folder (SKILL.md + scripts + reference files)
forge init my-agent --from-skill-dir ./path/to/skill-folder

# With builtin tools and registry skills
forge init my-agent \
  --framework custom \
  --model-provider openai \
  --tools web_search,http_request \
  --skills github \
  --api-key sk-... \
  --non-interactive

# OpenAI enterprise with organization ID
forge init my-agent \
  --model-provider openai \
  --api-key sk-... \
  --org-id org-xxxxxxxxxxxxxxxxxxxxxxxx \
  --non-interactive

# AWS IAM auth (any caller in account 412664885516)
forge init my-agent \
  --model-provider ollama \
  --auth=aws_sigv4 \
  --auth-aws-region=us-east-1 \
  --auth-aws-allowed-account=412664885516 \
  --non-interactive

# Azure AD multi-tenant with explicit partner allowlist
forge init my-agent \
  --model-provider ollama \
  --auth=azure_ad \
  --auth-azure-audience=api://forge \
  --auth-azure-multi-tenant \
  --auth-azure-allowed-tenant=00000000-1111-... \
  --auth-azure-allowed-tenant=55555555-6666-... \
  --non-interactive

# Interactive: resolves a credential, then chat
forge try

# One-shot (CI / docs / a quick check)
forge try --once "what's 17% of 4,200?"

# Keep the demo agent to make it your own (writes ./forge-quickstart)
forge try --keep

forge build [flags]

# Build with default config
forge build

# Build with custom config and output
forge build --config agent.yaml --output-dir ./build

# Build with a local binary override
forge build --local-bin forge=/path/to/linux/forge

# Build with Alpine base and slim image
forge build --alpine --slim

# Build with a custom security policy (e.g. acknowledged internal egress domains)
forge build --policy ./security-policy.yaml

forge validate [flags]

# Basic validation
forge validate

# Strict mode
forge validate --strict

# Check Command compatibility
forge validate --command-compat

forge run [flags]

# Run with defaults
forge run

# Run with mock tools on custom port
forge run --port 9090 --mock-tools

# Run with LLM provider and channels
forge run --provider openai --model gpt-4 --with slack

# Container deployment
forge run --host 0.0.0.0 --shutdown-timeout 30s

# Run with guardrails enforced
forge run --enforce-guardrails --env .env.production

# Run with custom CORS origins (for K8s ingress)
forge run --cors-origins 'https://app.example.com,https://admin.example.com'

# Run with OpenTelemetry tracing enabled (export to local collector)
forge run --otel-enabled \
  --otel-endpoint http://localhost:4318/v1/traces \
  --otel-sampler always_on

# Same, but service name + protocol override
forge run --otel-enabled \
  --otel-endpoint otel.example.com:4317 \
  --otel-protocol grpc \
  --otel-service-name my-agent-staging

forge serve [start|stop|status|logs] [flags]

# Start daemon (secure defaults: 127.0.0.1, 30s shutdown timeout)
forge serve

# Start on custom port
forge serve start --port 9090 --host 0.0.0.0

# Stop the daemon
forge serve stop

# Check status (PID, uptime, health)
forge serve status

# View recent logs (last 100 lines)
forge serve logs

forge export [flags]

# Export with defaults
forge export

# Pretty-print with embedded schemas
forge export --pretty --include-schemas

# Simulate Command import
forge export --simulate-import

forge package [flags]

# Build image with auto-detected builder
forge package

# Build and push to registry
forge package --registry ghcr.io/myorg --push

# Build for specific platform with no cache
forge package --platform linux/amd64 --no-cache

# Generate docker-compose with channels
forge package --with-channels

# Package with a local binary override
forge package --local-bin forge=/path/to/linux/forge

# Package with slim Alpine image
forge package --alpine --slim

forge schedule list

# List configured MCP servers + their discovered tools and auth status
forge mcp list

# Test a server connection (optionally invoke a tool)
forge mcp test <server>
forge mcp test <server> --call <tool> --args '{"key":"value"}'

# OAuth login for a server (type: oauth) — discovers endpoints via
# RFC 9728/8414 + dynamic client registration (RFC 7591) at first login
forge mcp login <server>

# Clear a stored MCP OAuth token
forge mcp logout <server>

forge tool list

forge tool describe <name>

forge channel add <slack|telegram>

forge channel serve <slack|telegram>

forge channel list

forge channel status

# Store a secret (prompts for value securely)
forge secret set OPENAI_API_KEY

# Store with inline value
forge secret set SLACK_BOT_TOKEN xoxb-...

# Retrieve a secret (shows source)
forge secret get OPENAI_API_KEY

# List all secret keys
forge secret list

# Delete a secret
forge secret delete OLD_KEY

# Agent-local secret
forge secret set API_KEY --local

# Print the stored token to stdout. Exits 1 with an actionable error
# when the file is absent.
forge auth show-token

# Generate a fresh 256-bit token, store it (overwriting any existing
# value), and print to stdout. Use for first-deploy bootstrap from a
# clean checkout.
forge auth mint-token

# Print a ready-to-apply Kubernetes Secret YAML containing the token.
# Default name and namespace match what `forge package` emits.
forge auth secret-yaml
forge auth secret-yaml --namespace prod
forge auth secret-yaml --name custom-secret-name

# Common one-liner: populate the Secret a `forge package` deploy
# expects from the local runtime.token.
forge auth secret-yaml | kubectl apply -f -

# Remove a stored LLM OAuth credential (default: openai) so the next
# `forge init` / `forge try` prompts you to sign in again.
forge auth logout
forge auth logout openai

# Generate an Ed25519 signing keypair
forge key generate

# Generate with a custom name
forge key generate --name ci-key

# Add a public key to the trusted keyring
forge key trust ~/.forge/signing-key.pub

# List signing and trusted keys
forge key list

# Add a skill from the registry (prompts for env vars, merges egress domains)
forge skills add <skill-name>

# Import an external skill folder (SKILL.md + scripts + reference files) into
# the current project; vendors files, merges egress, reports env requirements
forge skills import ./path/to/skill-folder
forge skills import ./path/to/skill-folder --name my-skill --overwrite
# Infer + inject requires.bins (python3/node) for a plain SKILL.md with no metadata.forge
forge skills import ./path/to/skill-folder --write-forge-meta

# List available skills
forge skills list

# Filter by category
forge skills list --category sre

# Filter by tags
forge skills list --tags kubernetes,incident-response

# Validate skill requirements
forge skills validate  # checks bins, env, invalid Input keys, missing/orphan scripts; non-zero exit on error

# Audit skill security
forge skills audit --embedded

# Sign a skill
forge skills sign

# Generate a signing key
forge skills keygen

# Generate trust report
forge skills trust-report

# Launch with defaults
forge ui

# Specify workspace and port
forge ui --dir /path/to/workspace --port 4200

# Launch without auto-opening browser
forge ui --no-open