Operator CLI Reference

The FrameWorks CLI is your swiss-army knife for platform management. Provisioning uses Ansible for some infrastructure tasks, while most commands run direct SSH or API calls.

Tip

Use frameworks menu to launch an interactive menu for exploring these commands.

Command Shape Source Of Truth

This page explains command intent, persona boundaries, and common workflows. It does not pin rendered CLI output. For exact flags, defaults, arguments, and output formats, run frameworks <command> --help with the CLI version you are operating. The docs test suite cross-checks documented commands and documented long flags against Cobra.

Global Flags

--config string     Path to config.yaml (default: $XDG_CONFIG_HOME/frameworks/config.yaml,
                    which resolves to ~/.config/frameworks/config.yaml when XDG is unset)
--context string    Context name for this invocation; overrides the saved current context
--output string     Output format: json|text (default: text)
--verbose, -v       Enable verbose logging

Run frameworks config path --kind config to print the canonical path the CLI is using right now, honoring any --config override.

Note: the manifest-source flags (--manifest, --gitops-dir, --github-repo, --github-ref, --cluster, --age-key, --github-app-id, --github-installation-id, --github-private-key) are persistent on the frameworks cluster command group — set on any cluster * subcommand. They are not global.

Command Catalog

frameworks commands prints the Cobra command tree for tools that need to discover available CLI paths and flags without hardcoding them.

frameworks commands
frameworks commands --output json
frameworks commands --include-hidden --output json

Personas and Access Modes

frameworks setup creates a context with a persona and an access mode. The persona captures the operator’s intent; the access mode controls how operator-originated CLI calls reach control-plane gRPC services.

Persona	Default shape	Typical commands
platform	Public Bridge plus GitOps-backed access to core services. Setup defaults to access_mode=ssh.	admin, services, dns doctor, mesh status, context check, cluster *
selfhosted	Public Bridge for a tenant-owned BYO edge footprint. The operator does not run Quartermaster or Foghorn.	login, edge deploy, local edge diagnostics
user	Public Bridge/account API only; this is the persona for someone who is not running their own edge node.	login, insights, Skipper, account-facing workflows

Access modes:

Mode	Behavior
local	Use the endpoint fields saved in the context. Existing contexts default to this when access_mode is absent.
ssh	Platform contexts load the saved GitOps manifest, merge hosts_file, locate the host running the service, and open an SSH local-forward for the gRPC call.
mesh	Platform contexts dial the manifest WireGuard address directly. Use this only from a machine already joined to the mesh.

frameworks context set-access-mode ssh
frameworks context check

For platform contexts, per-service non-local URLs saved with frameworks context set-url still override manifest-derived targets, but they must declare transport explicitly: use --tls for TLS endpoints or --allow-insecure for plaintext gRPC. Localhost defaults, manifest SSH tunnels, and mesh-derived addresses keep their established transport behavior. Localhost defaults are ignored in ssh and mesh modes so a newly created platform context does not accidentally dial the operator laptop for core services. Self-hosted/BYO edge contexts use Bridge and do not collect core gRPC endpoints.

Older configs that still say persona: edge are normalized to user; edge is not a user-facing persona.

Cluster Manifest-Source Flags

All frameworks cluster * subcommands share a persistent flag set for selecting the cluster manifest. The resolver picks the highest-priority input the operator provided (flag > env > the active context’s saved default > cwd heuristic).

Flag	Env var	Meaning
--manifest	FRAMEWORKS_MANIFEST	Path to a single cluster.yaml
--gitops-dir	FRAMEWORKS_GITOPS_DIR	Local gitops repo root (uses <dir>/clusters/<cluster>/cluster.yaml)
--github-repo	FRAMEWORKS_GITHUB_REPO	owner/repo to fetch from via GitHub App
--github-ref	FRAMEWORKS_GITHUB_REF	Branch/tag for --github-repo (default main)
--cluster	FRAMEWORKS_CLUSTER	Cluster name within the gitops repo
--age-key	SOPS_AGE_KEY_FILE	Age private key for SOPS-encrypted files
--ssh-key	—	SSH private key path, overriding ssh-agent/ssh config defaults
--github-app-id	FRAMEWORKS_GITHUB_APP_ID	GitHub App ID (for --github-repo)
--github-installation-id	FRAMEWORKS_GITHUB_INSTALLATION_ID	GitHub Installation ID
--github-private-key	FRAMEWORKS_GITHUB_PRIVATE_KEY	Path to GitHub App private-key PEM

Save defaults once with frameworks setup (interactive) or the non-interactive equivalents (frameworks context create <name> + frameworks context set-gitops-*). Explicit flags on a specific invocation always win over saved defaults.

Detection & Health Commands

frameworks cluster detect

Detect the current state of all services in the cluster using multi-method detection.

Usage:

frameworks cluster detect [flags]

Detection Methods:

1. Check inventory file (/etc/frameworks/inventory.json)
2. Check Docker containers
3. Check systemd services
4. Check listening ports
5. Try health endpoints
6. Try direct connections (DB, Kafka, etc.)

The text report groups discovered service state by host and detection method. Use --output json when a pipeline needs machine-readable state.

Flags: inherits the Cluster Manifest-Source Flags.

Examples:

# Detect all services (uses the active context's saved manifest source)
frameworks cluster detect

# Detect against a specific manifest
frameworks cluster detect --manifest production.yaml

# Detect against a local gitops repo
frameworks cluster detect --gitops-dir ~/work/gitops --cluster production

---

frameworks cluster doctor

Run read-only health checks across the cluster.

Usage:

frameworks cluster doctor [flags]

Checks:

• Infrastructure: Postgres/Yugabyte, ClickHouse, and Kafka broker connectivity
• Applications: Health endpoints for enabled services
• Interfaces: Health endpoints for enabled interfaces
• Observability: Health endpoints for enabled observability services
• Database migrations: Embedded PostgreSQL/YugabyteDB migrations compared against each configured database’s _migrations ledger

Note: This command checks migration ledger drift, not full physical schema introspection. For YugabyteDB clusters where the password is only in SOPS env_files, pass --deep so doctor can decrypt DATABASE_PASSWORD.

The report groups infrastructure, application, interface, observability, and migration-ledger checks. Use --output json when a pipeline needs the current result shape.

Flags: inherits the Cluster Manifest-Source Flags.

Examples:

# Full health check against the active context
frameworks cluster doctor

# Against a GitHub-sourced manifest
frameworks cluster doctor --github-repo org/gitops --cluster production

# With verbose output
frameworks cluster doctor --verbose

---

frameworks cluster status

Compare deployed service versions against the available versions for the cluster’s release channel.

frameworks cluster status
frameworks cluster status --manifest /etc/frameworks/cluster.yaml
frameworks cluster status --json

The report includes enabled services, interfaces, and observability workloads. It also prints control-plane readiness information when the active context has a system tenant ID from a previous provision run.

---

frameworks cluster preflight

Check host readiness before provisioning.

frameworks cluster preflight
frameworks cluster preflight --domain example.com

Checks Docker/Compose, service manager availability, disk space, standard edge ports, ulimits, Linux sysctls, /dev/shm, optional DNS resolution, and infrastructure connectivity when a manifest source is configured.

---

frameworks cluster drift

Survey observed service state and fail when it diverges from the manifest.

frameworks cluster drift
frameworks cluster drift --manifest /etc/frameworks/cluster.yaml
frameworks cluster drift --output json

Drift states include missing, stopped, wrong_mode, and wrong_version. This is the CI-friendly observed-state check; it exits non-zero when any divergence is found.

---

frameworks cluster diff

Typed change-kind survey: compare desired (manifest + release artifacts) against observed (sha256 of files on each host) for every service that has registered a fingerprinter.

frameworks cluster diff
frameworks cluster diff --only-services foghorn,bridge
frameworks cluster diff --only-hosts regional-eu-1
frameworks cluster diff --output json

Diff kinds: binary, env, unit, cert, infra, unknown. Services without a registered fingerprinter report unknown; cluster apply --confirm falls through to the heavy cluster provision path for them. Exits non-zero when any kind diff is detected.

---

frameworks cluster apply

Rolling-update planner that composes typed diffs (cluster diff) with per-service rolling-update strategy (max_unavailable, region_stagger, canary, primary_last). Per-service update_strategy blocks in the manifest override those defaults when a service needs a different rollout budget. Without --confirm it prints the plan and exits (dry-run). With --confirm it executes each host through the same role provisioner used by cluster provision, so binaries, env files, systemd units, handlers, and validation stay owned by the Ansible roles. The action label is reload when the diff is env-only on a SIGHUP-capable service; otherwise it is restart. After each wave, cluster apply waits for a per-service readiness gate (HTTP health for HTTP services, systemctl is-active otherwise) before advancing.

frameworks cluster apply
frameworks cluster apply --only-services foghorn,bridge
frameworks cluster apply --output json
frameworks cluster apply --confirm

--output json is a dry-run format only; --confirm --output json is rejected so execution logs cannot be mixed into structured plan JSON.

Hard rule: if any host has a diff classified as unknown or infra, the command refuses and lists those entries under Skipped — those go through cluster provision instead. This is the safety guarantee that keeps the fast path from attempting structural changes.

--confirm halts on the first host that fails its action or its readiness gate. Recovery is to fix the failing host and re-run cluster apply — the diff classifier only re-emits hosts that are still out of sync, so a second run resumes from where the first stopped.

---

Provisioning Commands

frameworks cluster provision

Deploy services to hosts based on the cluster manifest.

Usage:

frameworks cluster provision [flags]

Deployment Modes:

• Docker: Uses docker-compose files (default for most services)
• Native: Uses systemd units (for services with native binaries)

Process:

1. Load the cluster manifest and validate required GitOps mesh identity
2. Build an execution plan
3. Generate configuration files (docker-compose.yml or systemd units)
4. Transfer files to target hosts via SSH and provision (Ansible for some infra)
5. Start services
6. Validate health (unless --ignore-validation)
7. For application/all phases, run database init, static SQL seeds, service-owned bootstrap reconciliation, and edge release target sync

Flags:

• Inherits the Cluster Manifest-Source Flags.
• --only string - Phase to provision (infrastructure, applications, interfaces, all)
• --dry-run - Show what would be deployed without actually deploying
• --force - Force re-provision even if services exist
• --ignore-validation - Continue even if health validation fails (dangerous)
• --bootstrap-admin-* / --strict-control-plane - Optional bootstrap controls; see frameworks cluster provision --help for the full list.

Examples:

# Provision + init + static seeds + admin bootstrap in one shot
frameworks cluster provision \
  --bootstrap-admin-email you@co --bootstrap-admin-password-env DEPLOY_PW

# Provision entire cluster
frameworks cluster provision --gitops-dir gitops --cluster production

# Provision only infrastructure
frameworks cluster provision --only infrastructure

# Provision only applications
frameworks cluster provision --only applications

# Preview changes
frameworks cluster provision --dry-run

On success, the CLI remembers the manifest path and system tenant ID in the active context, so follow-up commands (cluster doctor, cluster status, admin users create) don’t need to re-specify them. When a saved default is used, the command announces it with Using manifest from context: … — explicit flags always win.

cluster provision is read-only against GitOps. For managed native clusters, run frameworks mesh wg generate and frameworks mesh wg check before provisioning; missing mesh identity is a hard preflight error.

Bootstrap Flow:

During provisioning, the CLI automatically bootstraps the system tenant and clusters:

1. Service Token: SERVICE_TOKEN is loaded from your manifest env_files (gitops, SOPS-encrypted) — the CLI decrypts with --age-key or SOPS_AGE_KEY_FILE and uses the token to authenticate to Quartermaster. No separate login or env var is required; the token is platform configuration, not operator identity.

2. System Tenant Creation: If the “FrameWorks” system tenant doesn’t exist, it’s created with deployment tier global.

3. Cluster Registration:

   • If the manifest has a clusters section, one cluster record is created per entry. Cluster IDs come from the manifest keys (e.g., prod-control, prod-media).
   • If there is no clusters section, a single cluster is created with ID {type}-{profile} (e.g., cluster-production).
   • Each cluster is registered with its name, type, and base URL derived from Bridge (if present) or Quartermaster.

4. Node Registration: Each host is registered under the cluster(s) its services belong to. The CLI resolves cluster assignment per service using role-based matching (see Cluster Manifest: clusters).

5. Infrastructure Bootstrap Tokens: One token is generated per cluster:

   • Kind: infrastructure_node
   • TTL: 720 hours (30 days)
   • Usage limit not set (defaults to single-use until used)

Important: When using clusters, IDs are explicit from the manifest. When not using clusters, the auto-generated format {type}-{profile} applies. These IDs are needed when using:

• admin bootstrap-tokens create --cluster-id
• services discover --cluster-id

To discover existing cluster IDs after provisioning:

frameworks admin clusters list

---

frameworks cluster finalize

Resume the post-provision control-plane finalization steps without provisioning or restarting services.

Usage:

frameworks cluster finalize [flags]

Process:

1. Load the cluster manifest and SOPS-backed env_files
2. Render the same bootstrap desired-state document used by provisioning
3. Run purser bootstrap and purser bootstrap validate
4. Run commodore bootstrap
5. Run control-plane validation

Flags:

• Inherits the Cluster Manifest-Source Flags.
• --only string - Finalization slice to run (all, purser, commodore, validation)
• --skip-validation - Skip final control-plane validation when --only=all
• --ignore-validation - Continue even if control-plane validation has warnings
• --bootstrap-admin-* / --bootstrap-reset-credentials / --strict-control-plane - Same bootstrap controls as cluster provision

Examples:

# Resume every post-provision finalization step
frameworks cluster finalize --gitops-dir gitops --cluster production

# Retry only Commodore bootstrap after fixing stale stream state
frameworks cluster finalize --gitops-dir gitops --cluster production --only commodore

# Run only the final control-plane validation
frameworks cluster finalize --gitops-dir gitops --cluster production --only validation

---

frameworks cluster init

Initialize databases and create required schemas/tables.

Usage:

frameworks cluster init [service] [flags]

Initialization:

• Creates PostgreSQL databases and schemas
• Creates ClickHouse databases and tables
• Creates Kafka topics
• Applies embedded schemas and static seeds (per service)

Flags:

• --manifest string - Cluster manifest file

Examples:

# Initialize everything
frameworks cluster init all

# Initialize just Postgres
frameworks cluster init postgres --manifest production.yaml

---

Additional Cluster Provisioning Commands

Command	Purpose
frameworks cluster finalize	Resume service-owned post-provision finalization without provisioning or restarting services; supports --only purser, --only commodore, and --only validation.
frameworks cluster seed	Apply idempotent static seed data; add --demo for sample tenant/user/stream data and --force to skip the prompt.
frameworks cluster migrate	Apply pending PostgreSQL/YugabyteDB schema migrations from pkg/database/sql/migrations/; use --phase expand --dry-run for Ansible check/diff mode. Filtered to --to-version vX.Y.Z (defaults to cluster’s resolved platform version).
frameworks cluster migrate validate	Validate migration path layout, checksums-at-source assumptions, and conservative expand-phase SQL safety rules.
frameworks cluster data-migrate list	List required data migrations declared in the embedded release catalog up to --to-version. Empty catalog reports “no required data migrations declared” — never silent OK.
frameworks cluster data-migrate status <service>.<id>	Show persisted state for one data migration on its owning service host (queries the service binary’s data-migrations status --format json).
frameworks cluster data-migrate run <service>.<id>	Run one data migration to completion or until error; honors --batch-size, --dry-run, --scope-kind/--scope-value.
frameworks cluster data-migrate verify <service>.<id>	Run the migration’s read-only verification on the service host.
frameworks cluster data-migrate pause <service>.<id>	Mark a data migration paused.
frameworks cluster data-migrate resume <service>.<id>	Mark a paused data migration runnable again.
frameworks cluster skipper knowledge reset	Clear Skipper knowledge embeddings and crawl cache so configured sources are fetched and embedded again.
frameworks cluster skipper posts	Query recent Skipper social post drafts from the skipper database over the manifest-selected SSH/database path.
frameworks cluster metabase sync	Sync repo-managed Metabase Periscope cards and attach missing cards to the dashboard without overwriting unmanaged manual edits.
frameworks cluster sync-geoip	Upload GeoLite2-City MMDB data to Foghorn/Quartermaster hosts; supports --source maxmind or --source file.
frameworks cluster set-channel <channel>	Set the manifest release channel. Valid channels are stable and rc; cluster upgrade uses this when no explicit version is given.

Examples:

# Static seeds only
frameworks cluster seed

# Include demo tenant/user/stream records
frameworks cluster seed --demo --force

# Preview migrations without applying them
frameworks cluster migrate --phase expand --dry-run

# Validate embedded migration files
frameworks cluster migrate validate

# Apply expand-compatible schema migrations
frameworks cluster migrate --phase expand

# Inspect recent Skipper social drafts
frameworks cluster skipper posts --status draft --limit 25

# Clear platform knowledge vectors and crawl cache before an embedding-model recrawl
frameworks cluster skipper knowledge reset --yes

# Adopt existing matching Metabase cards, then keep them managed by hash
frameworks cluster metabase sync \
  --url https://metabase.example.com \
  --session-id "$METABASE_SESSION_ID" \
  --adopt

# Distribute a local GeoIP database and restart target services
frameworks cluster sync-geoip \
  --source file \
  --file /path/to/GeoLite2-City.mmdb \
  --services foghorn,quartermaster \
  --restart

# Move the cluster onto the release-candidate channel
frameworks cluster set-channel rc

---

Operations Commands

frameworks cluster skipper

Inspect Skipper operational state.

frameworks cluster skipper knowledge reset

Clear Skipper knowledge embeddings and page-cache rows so the next crawl cycle fetches and embeds sources from scratch. The command does not delete conversations, usage rows, social posts, reports, or diagnostic baselines.

By default it resets the active context’s system tenant. Pass --tenant-id for a specific tenant, --all-tenants to reset every tenant, and --source to limit the reset to one source URL or source root.

Usage:

frameworks cluster skipper knowledge reset [flags]

Flags:

• --tenant-id string - Tenant UUID to reset (defaults to active context system tenant)
• --all-tenants - Reset knowledge for every tenant
• --source string - Limit reset to one source URL or source root
• --dry-run - Show matching row counts without deleting data
• --yes / -y - Skip confirmation prompt

Examples:

frameworks cluster skipper knowledge reset --dry-run
frameworks cluster skipper knowledge reset --yes
frameworks cluster skipper knowledge reset --tenant-id 00000000-0000-0000-0000-000000000001 --yes
frameworks cluster skipper knowledge reset --all-tenants --yes

frameworks cluster skipper posts

List recent Skipper social posts from skipper.skipper_posts.

Usage:

frameworks cluster skipper posts [flags]

Flags:

• --limit int - Maximum rows to show (default: 50, max: 500)
• --status string - Filter by post status, for example draft or sent

Examples:

frameworks cluster skipper posts
frameworks cluster skipper posts --status draft --limit 25

frameworks cluster metabase

Manage repo-owned Metabase content for a cluster.

frameworks cluster metabase sync

Sync the managed Periscope cards from infrastructure/metabase/periscope_cards.yaml to Metabase. The command creates missing cards and updates cards that still carry the Frameworks managed hash. Existing cards without that marker are left alone unless --adopt confirms the SQL already matches, or --force is used to replace them.

Usage:

frameworks cluster metabase sync [flags]

Flags:

• --url string - Metabase base URL (defaults to METABASE_URL)
• --session-id string - Metabase session ID (defaults to METABASE_SESSION_ID)
• --api-key string - Metabase API key (defaults to METABASE_API_KEY)
• --file string - Managed card spec file
• --database string / --database-id int - Target Metabase database
• --collection string / --collection-id int - Target collection
• --dashboard string / --dashboard-id int - Dashboard to attach cards to
• --dry-run - Print intended changes without writing
• --adopt - Mark matching unmanaged cards as Frameworks-managed
• --force - Replace existing unmanaged cards

Examples:

frameworks cluster metabase sync --url http://localhost:3001 --session-id "$METABASE_SESSION_ID" --dry-run
frameworks cluster metabase sync --url https://metabase.example.com --api-key "$METABASE_API_KEY" --adopt

frameworks cluster logs

View or stream service logs.

Usage:

frameworks cluster logs <service> [flags]

Supports:

• Docker Compose logs (docker compose logs)
• Systemd journal logs (journalctl -u)

Flags:

• --manifest string - Cluster manifest file
• --follow, -f - Follow log output (stream)
• --tail, -n int - Number of lines to show (default: 50)

Examples:

# View last 50 lines (default)
frameworks cluster logs commodore

# Stream logs
frameworks cluster logs commodore --follow

# Show last 500 lines
frameworks cluster logs bridge --tail 500

# Show last 100 lines and follow
frameworks cluster logs decklog -n 100 -f

frameworks cluster logs snapshot

Collect a bounded debugging snapshot from every cluster host. Each host gets a local log file with host metadata, failed units, frameworks-* service status, journal excerpts, suspicious log summaries, and internal PKI cert/key checks.

Usage:

frameworks cluster logs snapshot [flags]

Flags:

• --manifest string - Cluster manifest file
• --since string - Journal window when --boot is not set (default: 4 hours ago)
• --boot - Collect logs from the current boot instead of --since
• --tail int - Maximum journal lines per unit; set 0 for all lines in scope (default: 500)
• --output, -o string - Local output directory; defaults to a temp directory
• --parallel int - Maximum hosts to collect in parallel (default: 6)
• --edge-manifest string - Optional edge manifest to include edge nodes

Examples:

frameworks cluster logs snapshot --since "2 hours ago"
frameworks cluster logs snapshot --boot --tail 800 --edge-manifest ./clusters/production/edge.yaml
frameworks cluster logs snapshot --output /tmp/fw-logs

frameworks cluster snapshot

Collect a bounded incident bundle from the cluster manifest. The snapshot includes HA-aware host logs and read-only database metadata for PostgreSQL/YugabyteDB and ClickHouse: table sizes, row estimates, migration ledgers, ClickHouse parts, and pending mutations.

Usage:

frameworks cluster snapshot [flags]

Flags:

• --manifest string - Cluster manifest file
• --since string - Journal window when --boot is not set (default: 4 hours ago)
• --boot - Collect logs from the current boot instead of --since
• --tail int - Maximum journal lines per unit; set 0 for all lines in scope (default: 500)
• --output, -o string - Local output directory; defaults to a temp directory
• --parallel int - Maximum hosts to collect in parallel (default: 6)
• --edge-manifest string - Optional edge manifest to include edge nodes
• --skip-logs - Skip host and service logs
• --skip-db - Skip database metadata

Examples:

frameworks cluster snapshot --gitops-dir ../gitops --cluster production --since "2 hours ago"
frameworks cluster snapshot --boot --tail 800 --output /tmp/fw-snapshot
frameworks cluster snapshot --skip-logs --output /tmp/fw-db-state

---

frameworks cluster os

Run OS-level fleet maintenance operations.

frameworks cluster os update

Inspect or apply pending OS updates across manifest hosts. Check mode is the default and exits with code 2 when updates, stale services, or a reboot are pending. Apply mode is mutating and should run only during a maintenance window.

Usage:

frameworks cluster os update [flags]

Flags:

• --check - Inspect pending OS updates (default when --apply is absent)
• --refresh - Refresh apt indexes during check mode
• --apply - Apply package upgrades, restart stale services, and reboot when needed
• --hosts string - Comma-separated manifest host names to target
• --mode string - Apt upgrade mode for apply: safe or full (default: safe)
• --serial int - Number of hosts to process in parallel during apply (default: 1)
• --no-reboot - Skip reboot even if /var/run/reboot-required exists
• --continue-on-error - Continue after per-host failures during apply
• --json - Emit one JSON object per host in check mode

Examples:

# Inspect pending updates without refreshing apt indexes
frameworks cluster os update

# Refresh apt indexes first, then return exit code 2 if anything is pending
frameworks cluster os update --refresh

# Apply updates to one host without rebooting
frameworks cluster os update --apply --hosts central-eu-1 --no-reboot

---

frameworks cluster restart

Restart services with optional health validation.

Usage:

frameworks cluster restart <service> [flags]

Process:

1. Stop service gracefully
2. Wait for shutdown
3. Start service
4. Validate health (if enabled)

Flags:

• --manifest string - Cluster manifest file
• --validate - Validate service health after restart

Examples:

# Restart with health check
frameworks cluster restart commodore

# Restart with health validation
frameworks cluster restart bridge --validate

---

frameworks cluster upgrade

Upgrade services to new versions from GitOps manifests.

For the production rollout sequence, including migrations and rollback behavior, see Running Cluster Upgrades.

Usage:

frameworks cluster upgrade <service> [flags]

Version Resolution:

• stable - Latest stable release
• rc - Latest release candidate
• v0.0.0-rc1 - Specific version tag

Process:

1. Detect current state
2. Fetch GitOps manifest for target version
3. Stop service
4. Deploy new version (pull image or download binary)
5. Start service
6. Validate health

Flags:

• --manifest string - Cluster manifest file
• --version string - Target version. Defaults to the manifest release channel, or stable if no channel is set.
• --dry-run - Preview upgrade without executing
• --skip-validation - Skip health validation after upgrade
• --yes - Skip confirmation prompt
• --no-rollback - Skip automatic rollback on health check failure
• --all - Upgrade all enabled services in dependency order

Examples:

# Upgrade to latest stable
frameworks cluster upgrade commodore --version stable

# Upgrade to specific version
frameworks cluster upgrade bridge --version v0.0.0-rc1

# Show rollout order and embedded migration phases
frameworks cluster upgrade plan --version stable

# Preview upgrade
frameworks cluster upgrade signalman --version stable --dry-run

# Upgrade without validation
frameworks cluster upgrade decklog --version stable --skip-validation

# Upgrade all enabled services in dependency order
frameworks cluster upgrade --all --yes

Database schema changes

Service upgrades may require schema migrations. For ClickHouse changes, apply ALTER TABLE statements before upgrading services. See ClickHouse Migrations. For PostgreSQL/YugabyteDB migrations, run frameworks cluster migrate --phase expand --to-version vX.Y.Z before upgrading services that depend on the new schema. Upgrade commands run the same migration and data-migration gates in dry-run and apply mode.

Background data migration support

frameworks cluster data-migrate lists and runs service-owned background data migrations declared in the embedded release catalog. A declared migration that the target service cannot report is treated as a blocker, not as completed.

---

Backup & Restore Commands

frameworks cluster backup

Backup cluster components to local storage.

Usage:

frameworks cluster backup <component> [flags]

Components:

• postgres - PostgreSQL/YugabyteDB dump (pg_dumpall)
• clickhouse - ClickHouse databases (TSV format)
• volumes - Docker volumes (tar.gz archives)
• config - Configuration files (.env, docker-compose.yml, /etc/frameworks)
• all - Backup everything

Backups are local-only. The command writes timestamped artifacts under the selected output directory; treat the exact filenames as CLI-owned.

Flags:

• --manifest string - Cluster manifest file
• --output string - Output directory (default: ./backups)
• --skip-upload - Deprecated no-op; backups are local-only

Examples:

# Backup everything
frameworks cluster backup all --output /backups

# Backup only Postgres
frameworks cluster backup postgres --output /opt/backups

# Backup ClickHouse
frameworks cluster backup clickhouse --output /backups

# Backup volumes
frameworks cluster backup volumes --output /backups

# Backup config files
frameworks cluster backup config --output /backups

---

frameworks cluster restore

Restore components from backup files.

Usage:

frameworks cluster restore <component> [flags]

⚠️ Warning: Restore will STOP services and OVERWRITE existing data!

Components:

• postgres - Restore from SQL dump
• clickhouse - Restore from TSV directory
• volumes - Restore from tar.gz archive
• config - Restore configuration files

Flags:

• --manifest string - Cluster manifest file
• --from string - Path to backup file or directory (required)
• --skip-validation - Skip service health validation after postgres/clickhouse restore
• --yes - Skip confirmation prompt

Examples:

# Restore Postgres
frameworks cluster restore postgres \
  --from /backups/2025-01-17/postgres-20250117-143000.sql

# Restore ClickHouse
frameworks cluster restore clickhouse \
  --from /backups/2025-01-17/clickhouse-20250117-143000/

# Restore volumes
frameworks cluster restore volumes \
  --from /backups/2025-01-17/volumes-20250117-143000.tar.gz

# Restore config
frameworks cluster restore config \
  --from /backups/2025-01-17/config-20250117-143000.tar.gz

# Restore without validation
frameworks cluster restore postgres \
  --from /backups/postgres.sql --skip-validation

---

Diagnostic Commands

frameworks cluster diagnose network

Test network connectivity between all hosts in the cluster.

Usage:

frameworks cluster diagnose network [flags]

Tests:

• Ping test from each host to every other host
• Reports success/failure matrix

The report shows host-to-host connectivity results for the manifest targets.

Examples:

frameworks cluster diagnose network

---

frameworks cluster diagnose resources

Check CPU, memory, disk, and load average on all hosts.

Usage:

frameworks cluster diagnose resources [flags]

Metrics:

• CPU usage (%)
• Memory usage (used/total)
• Disk usage (/)
• Load average (1m, 5m, 15m)

The report shows CPU, memory, disk, and load data for each manifest host.

Examples:

frameworks cluster diagnose resources

---

frameworks cluster diagnose ports

Check for port conflicts on all hosts.

Usage:

frameworks cluster diagnose ports [flags]

Checks Standard Ports: Uses the CLI’s built-in port list for core services, interfaces, and gRPC endpoints. For the canonical port table, see Architecture Overview.

The report checks the CLI’s built-in port set against each manifest host.

Examples:

frameworks cluster diagnose ports

---

frameworks cluster diagnose kafka

Check Kafka cluster health, topics, consumer groups, and broker status.

Usage:

frameworks cluster diagnose kafka [flags]

Checks:

• List all topics
• List consumer groups
• Broker API version check
• Cluster responsiveness

The report covers topic listing, consumer groups, broker API reachability, and cluster responsiveness for the configured Kafka target.

Examples:

frameworks cluster diagnose kafka

---

DNS Commands

frameworks dns doctor

Verify public DNS records match Quartermaster inventory.

Usage:

frameworks dns doctor --domain example.com

Compares expected IPs from node inventory against actual DNS resolution. Useful for verifying Navigator has synced DNS records correctly.

---

Mesh Commands

frameworks mesh wg generate

Generate missing GitOps WireGuard identity for cluster hosts. This intentionally writes cluster.yaml and the local SOPS hosts inventory.

frameworks mesh wg generate \
  --manifest gitops/clusters/production/cluster.yaml \
  --hosts-file gitops/clusters/production/hosts.enc.yaml

Mutation commands require a local checkout. Remote GitHub sources are rejected; run them against a checked-out gitops repository, review the diff, then commit.

frameworks mesh wg check

Read-only validation for CI and preflight.

frameworks mesh wg check --gitops-dir gitops --cluster production

frameworks mesh wg rotate

Rotate one host’s WireGuard key. The mesh IP is preserved by default; pass --readdress only when the address must change.

frameworks mesh wg rotate core-2 --gitops-dir gitops --cluster production

frameworks mesh status

Show WireGuard mesh status from Quartermaster inventory.

Usage:

frameworks mesh status

Displays node IDs, roles, internal/WireGuard IPs, last heartbeat, and agent status. Useful for verifying Privateer mesh connectivity.

---

Additional Mesh Commands

Command	Purpose
frameworks mesh doctor	Simulate Privateer’s runtime WireGuard apply policy for each manifest host and report validation failures.
frameworks mesh join <ssh-target>	Write Privateer’s runtime-enrollment env file to a remote host over SSH. Requires --token and --bootstrap-addr.
frameworks mesh reconcile	Adopt runtime_enrolled nodes into GitOps. Use --write-gitops to mutate cluster.yaml and hosts.enc.yaml.
frameworks mesh wg audit	Compare GitOps WireGuard identity against Quartermaster node state; exits non-zero on authoritative divergence.
frameworks mesh wg promote <host>	Finish adopted_local to gitops_seed promotion after mesh wg rotate and cluster provision converge.

Examples:

frameworks mesh doctor --gitops-dir gitops --cluster production
frameworks mesh wg audit --gitops-dir gitops --cluster production
frameworks mesh join root@edge-2 \
  --token <bootstrap-token> \
  --bootstrap-addr https://bridge.example.com \
  --cluster-id production
frameworks mesh reconcile --write-gitops --gitops-dir gitops --cluster production
frameworks mesh wg promote edge-2 --gitops-dir gitops --cluster production

---

Admin Commands

frameworks admin tokens

Manage developer API tokens.

Subcommands:

# Create a token
frameworks admin tokens create --name "my-app" --expires 720h --perms "read:streams,write:streams"

# List tokens (shows name and ID)
frameworks admin tokens list

# Revoke by name (preferred)
frameworks admin tokens revoke --name "my-app"

# Revoke by ID
frameworks admin tokens revoke <token-id>

Flags for create:

• --name - Token name/label (required)
• --expires - Expiry duration (e.g., 720h, 30d)
• --perms - Comma-separated permissions

Note: Permissions are accepted but not enforced yet. API tokens currently grant full access until RBAC lands.

---

frameworks admin bootstrap-tokens

Manage bootstrap tokens for edge node enrollment.

Subcommands:

# Create bootstrap token
frameworks admin bootstrap-tokens create --name "edge-nyc-01" --kind edge_node --ttl 24h

# Create runtime mesh token with pre-service topology intent
frameworks admin bootstrap-tokens create \
  --name "regional-eu-2 privateer" \
  --kind infrastructure_node \
  --cluster-id regional-eu-1 \
  --desired-service-type foghorn \
  --desired-cluster-id media-eu-1

# List tokens (shows name and ID)
frameworks admin bootstrap-tokens list

# Revoke by name (preferred)
frameworks admin bootstrap-tokens revoke --name "edge-nyc-01"

# Revoke by ID
frameworks admin bootstrap-tokens revoke <token-id>

Flags for create:

• --name - Display name (required)
• --kind - Token kind: edge_node, service, or infrastructure_node (default: edge_node)
• --ttl - Time-to-live (e.g., 24h, 7d) (default: 24h)
• --tenant-id - Tenant ID (required for edge_node)
• --cluster-id - Cluster ID (required for edge_node)
• --expected-ip - Expected client IP for validation (optional)
• --usage-limit - Maximum uses; omit or set 0 for single use

---

frameworks admin tenants

List and manage tenants.

# List all tenants (shows name and ID)
frameworks admin tenants list

Sample output:

Tenants (2)
 - FrameWorks (id=abc123-...) tier=global
 - Acme Corp (id=def456-...) tier=standard

---

frameworks admin clusters

List and manage clusters.

Subcommands:

• list - List clusters
• create - Create a cluster
• update - Update a cluster
• access - Manage tenant access (frameworks admin clusters access list, frameworks admin clusters access grant)
• invites - Manage invites (frameworks admin clusters invites create, frameworks admin clusters invites list, frameworks admin clusters invites revoke, frameworks admin clusters invites list-mine, frameworks admin clusters invites accept)
• subscriptions - List cluster subscriptions (frameworks admin clusters subscriptions list)
• migrate-artifacts - Migrate artifact metadata from a source cluster for one tenant

# List all clusters (shows name and ID)
frameworks admin clusters list

# Create an internal cluster
frameworks admin clusters create \
  --cluster-id central-production \
  --cluster-name "FrameWorks Central Production" \
  --cluster-type central \
  --base-url http://10.0.1.10:18002

# Create a customer-facing media cluster with Foghorn and platform flags
frameworks admin clusters create \
  --cluster-id edge-eu \
  --cluster-name "EU Edge Cluster" \
  --cluster-type edge \
  --base-url eu.frameworks.network \
  --foghorn-count 2 \
  --is-platform-official \
  --is-default-cluster

# Update cluster flags
frameworks admin clusters update --cluster-id edge-eu --is-platform-official
frameworks admin clusters update --cluster-id edge-eu --is-default-cluster

# Grant a tenant access to a private/unlisted cluster
frameworks admin clusters access grant --cluster-id edge-eu --tenant-id <tenant-id>

# List cluster access rows for a tenant
frameworks admin clusters access list --tenant-id <tenant-id>

# Create and accept an invite
frameworks admin clusters invites create \
  --cluster-id edge-eu \
  --owner-tenant-id <owner-tenant-id> \
  --invited-tenant-id <invited-tenant-id>
frameworks admin clusters invites list --cluster-id edge-eu --owner-tenant-id <owner-tenant-id>
frameworks admin clusters invites list-mine --tenant-id <tenant-id>
frameworks admin clusters invites accept --invite-token <invite-token>
frameworks admin clusters invites revoke --invite-id <invite-id> --owner-tenant-id <owner-tenant-id>

# List cluster subscriptions for a tenant
frameworks admin clusters subscriptions list --tenant-id <tenant-id>

# Migrate artifact metadata after moving a tenant between clusters
frameworks admin clusters migrate-artifacts \
  --tenant-id <tenant-id> \
  --from-cluster <source-cluster-id>

Sample output:

Clusters (2)
 - FrameWorks Central Production (id=central-production) type=central url=http://10.0.1.10:18002
 - FrameWorks Regional EU (id=regional-eu) type=regional url=http://10.1.1.10:18002

Note: Cluster IDs are either explicit (from the clusters section of your manifest) or auto-generated as {type}-{profile} when no clusters section is defined.

---

frameworks admin service-pool

Manage pool-assigned media services across logical clusters.

Subcommands:

# Show pool status (total, assigned, unassigned per cluster)
frameworks admin service-pool status --service-type foghorn

# Release instances back to the pool
frameworks admin service-pool add --service-type foghorn --instance-id <uuid>
frameworks admin service-pool add --service-type livepeer-gateway --count 2 --from-cluster <cluster-id>

# Drain an instance from its cluster
frameworks admin service-pool drain --service-type chandler --instance-id <uuid>

# Assign service instance(s) to a cluster (many-to-many)
frameworks admin service-pool assign --service-type foghorn --cluster-id <id> --count 1
frameworks admin service-pool assign --service-type livepeer-gateway --cluster-id <id> --instance-id <uuid>

# Remove service instance(s) from a cluster
frameworks admin service-pool unassign --service-type chandler --cluster-id <id> --instance-id <uuid>

Flags for add:

• --instance-id - Instance UUID(s) to release (repeatable)
• --count - Number of instances to release from cluster
• --from-cluster - Cluster to release instances from

Requires either --instance-id or both --count and --from-cluster.

Flags for assign:

• --cluster-id - Cluster to assign Foghorn(s) to (required)
• --instance-id - Specific Foghorn instance UUID(s) (repeatable)
• --count - Pick N least-loaded Foghorn instances

Flags for unassign:

• --cluster-id - Cluster to unassign from (required)
• --instance-id - Foghorn instance UUID(s) to remove (required)

Flags for drain:

• --instance-id - Instance UUID to drain (required)

---

frameworks admin clusters create-edge

Create an edge cluster with automatic Foghorn assignment and enrollment token.

frameworks admin clusters create-edge --cluster-name "My Edge" --tenant-id <uuid>

Flags:

• --cluster-name - Display name for the cluster (required)
• --tenant-id - Tenant ID (defaults to JWT tenant)
• --description - Short description

---

frameworks admin clusters enrollment-token

Create an enrollment token for an existing cluster. Requires cluster owner/operator or provider lifecycle authority; ordinary subscriber access cannot mint node enrollment tokens.

frameworks admin clusters enrollment-token --cluster-id <id> --ttl 7d

Flags:

• --cluster-id - Cluster ID (required)
• --tenant-id - Tenant ID (defaults to JWT tenant)
• --name - Token display name
• --ttl - Time-to-live (e.g. 24h, 7d; default 30d)

---

frameworks admin clusters cert-status

Show cluster readiness including health, Foghorn instances, and certificate status.

frameworks admin clusters cert-status --cluster-id <cluster-id>

Flags:

• --cluster-id - Cluster ID (required)

Output includes: cluster name, type, base URL, health status, registered Foghorn instances with status, and certificate readiness.

---

frameworks admin billing

Billing tier and subscription management.

Subcommands:

• tiers - List billing tiers (shows default prepaid/postpaid flags)
• init-postpaid - Initialize postpaid billing for a tenant (resolves default postpaid tier, provisions cluster access)
• promote - Promote tenant from prepaid to postpaid billing (re-evaluates cluster subscriptions)
• set-cluster-pricing - Set or update pricing config for a cluster

# List billing tiers
frameworks admin billing tiers

# Initialize postpaid account for a tenant
frameworks admin billing init-postpaid --tenant-id <UUID>

# Promote prepaid tenant to postpaid
frameworks admin billing promote --tenant-id <UUID>

# Set cluster pricing (for marketplace or custom cluster billing)
frameworks admin billing set-cluster-pricing \
  --cluster-id <id> \
  --pricing-model tier_inherit \
  --required-tier-level 0 \
  --allow-free-tier

---

frameworks admin users

Manage users in existing tenants.

Subcommands:

• create - Create a user in an existing tenant (requires service token auth)

# Right after cluster provision — tenant-id comes from context, password from stdin
echo "$DEPLOY_PW" | frameworks admin users create --email [email protected] --password-stdin --role owner

# Or with an explicit tenant (overrides context default)
frameworks admin users create \
  --tenant-id <UUID> \
  --email [email protected] \
  --password <password> \
  --role owner

Flags:

• --tenant-id - Existing tenant UUID. Defaults to the active context’s SystemTenantID (populated by a successful cluster provision); override to target a different tenant.
• --email (required) - User email address
• --password - User password (plaintext; leaks into shell history — prefer --password-stdin).
• --password-stdin - Read password from stdin (recommended for CI).
• --first-name - First name
• --last-name - Last name
• --role - owner or member (default: owner)

Without --password or --password-stdin, the CLI prompts at a TTY with hidden echo.

---

frameworks admin nodes

List registered infrastructure nodes.

Subcommands:

• list - List nodes
• create - Create/register a node record
• hardware - Update hardware metadata (cpu/mem/disk)

# List all nodes
frameworks admin nodes list

# Filter by cluster
frameworks admin nodes list --cluster-id cluster-production

# Filter by type
frameworks admin nodes list --type edge

# Filter by region
frameworks admin nodes list --region us-east-1

# Create a node
frameworks admin nodes create \
  --node-name edge-nyc-01 \
  --node-type edge \
  --cluster-id central-production

# Update hardware metadata
frameworks admin nodes hardware --node-id edge-nyc-01 --cpu-cores 16 --memory-gb 64 --disk-gb 2000

Flags:

• --cluster-id - Filter by cluster ID
• --type - Filter by node type (common: edge, core; some deployments use regional/central)
• --region - Filter by region

---

Cluster Node Lifecycle Commands

Use frameworks cluster nodes ... for provider/operator edge-node lifecycle operations in platform-managed clusters. These commands require a platform context because they call Quartermaster and Foghorn directly with GitOps/service-token backed control-plane access. BYO edge operators should use frameworks edge deploy, which goes through Bridge instead of direct core gRPC. The commands default to the active context’s cluster_id; when a TTY has no active cluster, the CLI prompts for one. Pass --cluster-id when scripting against another cluster.

frameworks cluster nodes add --ssh [email protected]
frameworks cluster nodes list
frameworks cluster nodes drain --node edge-1
frameworks cluster nodes resume --node edge-1
frameworks cluster nodes remove --node edge-1 --wait 4h
frameworks cluster nodes evict --node edge-1

add expands an existing platform-managed cluster. It uses the active context’s cluster_id or prompts for a cluster on TTYs, mints a short-lived enrollment token internally through Quartermaster, passes it into the edge deployment pipeline, and does not print the token. Quartermaster requires provider authority for this path; ordinary tenant subscriptions cannot mint node enrollment tokens. Lifecycle-managed adds default to native mode and, unless --version is supplied, install from the cluster’s release target. Clusters without a release target use the stable manifest. Pass --mode docker only for nodes managed outside the agent-pull release reconciler. Before provisioning, it probes the target for an existing FrameWorks edge stack and classifies clean, complete same-cluster, foreign, partial, and unmarked installs. Foreign clusters are refused. Same-cluster targets are treated as already added only when the stack and node marker are present, Quartermaster still has an active node registration, and Foghorn reports live node health. Partial installs, stale markers, missing registrations, non-active registry status, and unmarked installs require --force-reapply after operator confirmation. User contexts are for hosted account, insights, and Skipper workflows, not edge-node lifecycle mutation.

Node-targeted commands accept --node <name-or-id> and prompt with an interactive cluster picker, then an interactive node picker, on TTYs when no context cluster or selector is provided. --node-id remains as a deprecated scripting alias.

drain and resume map to Foghorn operational modes. remove drains by default, waits up to 4 hours for active streams to reach zero unless --wait changes the deadline, switches the node to maintenance, and marks the Quartermaster registry row retired. remove --wait 0 is rejected; use evict when the intent is immediate fencing. evict immediately switches to maintenance and marks the registry row evicted.

list --health includes Foghorn mode/stream health and reported component versions. Helmsman reports component versions in its lifecycle heartbeat; Foghorn stores them in foghorn.node_components and returns them through node health.

frameworks cluster releases

Inspect and repair the edge release catalog and active cluster rollout target. Provider/platform contexts use Quartermaster through the configured control-plane resolver.

frameworks cluster releases list
frameworks cluster releases publish --version stable
frameworks cluster releases target get
frameworks cluster releases target set --channel stable --version v1.2.3
frameworks cluster releases target sync

frameworks cluster releases list

List known edge releases. Use --channel and --version to narrow the catalog.

frameworks cluster releases publish

Fetch a GitOps release manifest and publish its edge component catalog into Quartermaster. Use --version for the GitOps release version or channel. By default the catalog records every platform artifact in the manifest; --os and --arch narrow a repair/backfill publish to one platform. This is the provider repair/backfill path. Normal provider cluster provision and cluster upgrade --all runs publish the selected GitOps manifest and sync cluster targets automatically without clearing an operator pause or rollout override. Release rows must include at least one updateable edge component (helmsman, mist, or caddy); config-schema-only rows are rejected because runtime configuration still flows through ConfigSeed. Operators do not label releases to change rollout behavior; disruptive Mist behavior requires a CI-generated update contract.

frameworks cluster releases target

Inspect or override a cluster’s desired edge release target.

frameworks cluster releases target get

Show the active cluster’s release target. Pass --cluster-id to inspect a different cluster.

frameworks cluster releases target set

Set the active cluster’s target release track, optional pinned version, and rollout plan JSON. Pass --cluster-id when scripting. This is an override/repair path; provider cluster provision follows the manifest channel, and cluster upgrade --all syncs the target after the platform upgrade succeeds. Foghorn reconciles targets against reported node component versions and runtime platform metadata. Docker-mode edge nodes are not selected for native artifact convergence. Helmsman and Caddy changes apply over the existing Helmsman control stream, while Mist normally replaces the complete binary set atomically and sends USR1 to MistController so new child processes use the new binaries without draining the node. Cordon, drain, update, warmup version confirmation, endpoint probing, and return-to-normal are reserved for Mist releases whose CI-generated update contract explicitly requires a disruptive apply strategy. Config-schema versions are reported for visibility; actual runtime config still flows through ConfigSeed.

frameworks cluster releases target sync

Publish the selected GitOps release manifest and sync every manifest cluster’s edge release target. Use --version to override the manifest channel with a specific GitOps version or release channel. This is the targeted repair command for the same edge release target sync that cluster provision and cluster upgrade --all run automatically. Supported rollout-plan controls are limited to implemented scheduler behavior such as batch_size, canary, canary_count, error_abort, and max_failed; capacity-floor fields are rejected until disruptive drain rollouts need them.

---

Edge Commands

Edge node lifecycle operations. Most commands support --ssh user@host (and --ssh-key) for remote execution.

frameworks edge deploy

Deploy an edge node in one command. Handles edge cluster setup, enrollment token generation, pre-registration, and provisioning.

Mode A — Logged-in tenant (automatic cluster setup):

# Deploys to your edge cluster (creates one if needed)
frameworks edge deploy --ssh ubuntu@edge-1 --email [email protected]

# Deploy to a specific cluster
frameworks edge deploy --cluster-id my-edge-prod --ssh ubuntu@edge-1

Mode B — Pre-existing token:

frameworks edge deploy --enrollment-token <token> --ssh ubuntu@edge-1

The token is the only credential you need. Bridge resolves the cluster’s Foghorn via the public bootstrapEdge mutation and proxies the pre-registration. No Foghorn address required.

Flags:

• --cluster-id - Cluster to deploy to (auto-detected or auto-created if omitted)
• --cluster-name - Name for new edge cluster if one needs to be created
• --enrollment-token - Pre-existing enrollment token (skips login and cluster setup)
• --foghorn-addr - Explicit Foghorn gRPC override; debug only. Bridge resolves the addr by default; use this when you need to talk to a specific Foghorn directly.
• --ssh - SSH target (user@host) for remote deployment
• --ssh-key - SSH private key path
• --mode - Deployment mode: docker (default) or native
• --email - ACME email for TLS certificates
• --tune - Apply sysctl/limits tuning (default: true)
• --skip-preflight - Skip preflight checks
• --version - Platform version for binary resolution
• --timeout - HTTPS verification timeout (default: 3m)
• --token-ttl - Enrollment token TTL when --cluster-id mints a token

---

frameworks edge preflight

Check host readiness (DNS, ports, sysctl, ulimits).

# Check all requirements
frameworks edge preflight

# Include DNS validation for a specific domain
frameworks edge preflight --domain edge1.example.com

Flags:

• --domain - Edge domain to validate DNS for

---

frameworks edge tune

Apply recommended sysctl and ulimit settings for streaming workloads.

# Preview changes (writes local preview files)
frameworks edge tune

# Apply changes system-wide (requires sudo)
frameworks edge tune --write

Flags:

• --write - Write to system paths (requires sudo)
• --sysctl-path - Target sysctl path (default: /etc/sysctl.d/frameworks-edge.conf)
• --limits-path - Target limits path (default: /etc/security/limits.d/frameworks-edge.conf)

Tuning Applied:

• net.core.rmem_max = 16777216
• net.core.wmem_max = 16777216
• net.core.somaxconn = 8192
• net.ipv4.ip_local_port_range = 16384 65535
• * soft nofile = 1048576
• * hard nofile = 1048576

---

frameworks edge init

Generate edge node configuration files (edge env file, edge compose file, Caddy config file).

# With explicit domain
frameworks edge init --domain edge1.example.com --email [email protected]

# With enrollment token (auto-assigns domain via PreRegisterEdge)
frameworks edge init --enrollment-token enroll_abc123 --email [email protected]

When --enrollment-token is provided without --domain, the CLI calls PreRegisterEdge to get an auto-assigned domain, pool domain, and cluster configuration. The token carries tenant and cluster scope.

Flags:

• --dir - Target directory for templates (default: .)
• --domain - Edge domain to configure
• --enrollment-token - Enrollment token issued by FrameWorks for node bootstrap
• --email - ACME email for Let’s Encrypt certificate issuance
• --overwrite - Overwrite existing files

---

frameworks edge enroll

Start the edge stack and verify HTTPS readiness. The bootstrap token must be set in the edge environment file as EDGE_ENROLLMENT_TOKEN.

# Enroll edge node (token read from edge environment file)
frameworks edge enroll

# From a specific directory
frameworks edge enroll --dir /opt/frameworks-edge

# Run remotely via SSH
frameworks edge enroll --dir /opt/frameworks-edge --ssh [email protected]

Flags:

• --dir - Directory containing the edge compose and environment files
• --timeout - Maximum time to wait for HTTPS readiness (default: 2m)
• --ssh - Run remotely on user@host via SSH
• --ssh-key - SSH private key path

Note: This command starts Caddy, MistServer, and Helmsman, then waits for HTTPS to become available.

---

frameworks edge provision

Orchestrate full edge node provisioning (preflight, tune, register, init, enroll).

Usage:

# Single node provisioning
frameworks edge provision --ssh user@host [flags]

# Multi-node provisioning from manifest
frameworks edge provision --manifest edges.yaml

Process:

1. Run preflight checks
2. Apply system tuning (optional)
3. Register node in Quartermaster (optional)
4. Deliver enrolled TLS/CA/site config through Foghorn ConfigSeed
5. Generate and upload templates
6. Start edge stack
7. Verify HTTPS readiness

Flags:

• --ssh string - SSH target (user@host)
• --ssh-key - SSH private key path
• --pool-domain string - Shared edge pool domain (e.g., edge.media-eu.example.com)
• --node-domain string - Individual node domain
• --node-name string - Node name for registration
• --cluster-id string - Cluster ID for registration
• --region string - Region identifier
• --email string - ACME email for certificates
• --timeout - HTTPS readiness timeout (default: 3m)
• --enrollment-token string - Enrollment token for auto-provisioning (skips explicit domain flags)
• --manifest string - Path to edge manifest file
• --cluster-manifest string - Cluster manifest used to load platform SERVICE_TOKEN for edge manifest register_qm
• --parallel int - Number of concurrent provisions (default: 1)
• --tune - Apply sysctl/limits tuning
• --register - Register node in Quartermaster (manual/admin path only — see note below)
• --fetch-cert - Fetch TLS certificate from Navigator
• --skip-preflight - Skip preflight checks
• --capability string - Enabled capability for single-node provisioning; repeat for ingest, edge, storage, processing
• --bandwidth-mbps int - Advertised edge bandwidth limit in Mbps; Helmsman writes it to MistServer bwlimit and reports it to Foghorn
• --max-transcodes int - Maximum local transcodes reported by Helmsman
• --storage-capacity-bytes uint - Local storage capacity limit reported by Helmsman

--register is for the platform manual provisioning path, where an admin supplies --pool-domain/--node-domain directly without an enrollment token and wants to create the Quartermaster node row in the same step. It is rejected unless the active context uses the platform persona, and it is rejected when combined with --enrollment-token because the token path already registers the node through Foghorn’s PreRegisterEdge. Manifest entries that set register_qm: true follow the same platform-only rule and cannot be combined with an enrollment token.

Examples:

# Provision single node with explicit domains (manual/admin path; requires
# a platform context with Quartermaster reachability)
frameworks edge provision --ssh [email protected] \
  --pool-domain edge.media-eu.example.com \
  --node-domain edge-1.media-eu.example.com \
  --register --fetch-cert --email [email protected]

# Provision with enrollment token (auto-assigns domain via PreRegisterEdge,
# registers the node row as a side effect — do NOT pass --register)
frameworks edge provision --ssh [email protected] \
  --enrollment-token enroll_abc123 \
  --email [email protected]

# Provision from manifest
frameworks edge provision --manifest edges.yaml --parallel 4

When --enrollment-token is provided without --pool-domain and --node-domain, the CLI calls PreRegisterEdge to validate the token and get auto-assigned domains, the initial internal CA bundle, and cluster routing information.

---

frameworks edge status

Check edge node container status and HTTPS health.

frameworks edge status
frameworks edge status --domain edge1.example.com --ssh [email protected]

Flags:

• --dir - Directory with compose/env files
• --domain - Override EDGE_DOMAIN from env file
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks edge update

Update edge node software to latest version.

frameworks edge update
frameworks edge update --ssh [email protected]

Flags:

• --dir - Directory
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks edge cert

Check and manage TLS certificates.

frameworks edge cert --domain edge1.example.com
frameworks edge cert --reload  # Reload Caddy after check

Flags:

• --dir - Directory
• --domain - Domain to check
• --reload - Reload Caddy after certificate check
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks edge logs

View edge service logs.

frameworks edge logs
frameworks edge logs --follow --tail 500

Flags:

• --dir - Directory
• --follow - Follow/tail logs
• --tail - Number of lines to show
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks edge doctor

Run comprehensive health checks on the edge node.

frameworks edge doctor --domain edge1.example.com

Flags:

• --dir - Directory
• --domain - Domain to check

---

Additional Edge Commands

Command	Purpose
frameworks edge drift	Survey observed edge service state, .edge.env keys, and HTTPS health; exits non-zero on divergence.
frameworks edge diagnose media	Run MistServer media diagnostics, including HLS validation and analyzer checks for active or specified streams.
frameworks edge mist	MistServer-specific edge diagnostics.
frameworks edge mist cores	Collect and analyze MistController core dumps.
frameworks edge mode [mode]	Read or change Helmsman node mode. Valid modes are normal, draining, and maintenance.

Examples:

frameworks edge drift --dir /opt/frameworks-edge --ssh [email protected]
frameworks edge diagnose media --ssh [email protected]
frameworks edge diagnose media \
  --analyzer HLS \
  --target http://localhost:8080/hls/live/index.m3u8
frameworks edge mode draining --reason deploy --ssh [email protected]

frameworks edge mist cores collect

Collect the latest MistController core dump, MistServer artifact manifest, config snapshot, and service logs from a native edge over SSH.

frameworks edge mist cores collect [email protected]
frameworks edge mist cores collect [email protected] --out ./edge1-mist-core.tar.gz

Flags:

• --out - Local output tarball path
• --service - systemd unit to include in logs
• --since - journalctl time window to include
• --ssh-key - SSH private key path

frameworks edge mist cores analyze

Analyze a collected MistController core bundle. If the bundle contains a MistServer artifact manifest with a debug-symbol artifact URL, the CLI downloads the matching symbols into the local cache before invoking gdb or lldb.

frameworks edge mist cores analyze ./edge1-mist-core.tar.gz
frameworks edge mist cores analyze ./edge1-mist-core.tar.gz --cache-dir ~/.cache/frameworks/mistserver-debug

Flags:

• --cache-dir - Debug symbol cache directory

---

Livepeer Commands

Livepeer gateway management. Uses Quartermaster service discovery by default; override with --gateway host:port.

frameworks livepeer status

Show gateway status (version, ETH address, deposit info).

frameworks livepeer status
frameworks livepeer status --gateway 10.0.1.5:8935
frameworks livepeer status --cluster edge-us-east

Flags:

• --gateway - Gateway address (host:port), bypasses discovery
• --cluster - Cluster ID for discovery

frameworks livepeer deposit fund

Fund the TicketBroker deposit.

frameworks livepeer deposit fund --amount 1000000000000000000

Flags:

• --amount (required) - Amount in wei

frameworks livepeer deposit reserve

Fund both deposit and reserve.

frameworks livepeer deposit reserve --deposit 1000000000000000000 --reserve 500000000000000000

Flags:

• --deposit (required) - Deposit amount in wei
• --reserve (required) - Reserve amount in wei

frameworks livepeer deposit unlock

Start the unlock period for deposit and reserve.

frameworks livepeer deposit unlock

frameworks livepeer deposit withdraw

Withdraw unlocked deposit and reserve.

frameworks livepeer deposit withdraw

frameworks livepeer wallet address

Show the gateway’s ETH address.

frameworks livepeer wallet address

frameworks livepeer wallet balance

Show the gateway’s ETH balance.

frameworks livepeer wallet balance

---

Services Commands

Central-tier service operations (for single-host or development deployments).

frameworks services plan

Generate central-tier compose fragments and a .central.env file.

# Generate with default profile
frameworks services plan

# Use a specific profile
frameworks services plan --profile control-core

# Interactive service selection
frameworks services plan --interactive

# Include/exclude specific services
frameworks services plan --include commodore,quartermaster --exclude purser

The command writes service fragments and a merged central env file into the selected target directory. Exact filenames are CLI-owned; inspect frameworks services plan --help before scripting against them.

Flags:

• --profile - Preset: central-all | control-core | routing-only | analytics-suite | billing-only (default: central-all)
• --include - Comma-separated services to include
• --exclude - Comma-separated services to exclude
• --dir - Target directory for generated files (default: .)
• --overwrite - Overwrite existing files
• --interactive - Interactive checkbox selection
• --config-base - Path to base env file (default: config/env/base.env)
• --config-secrets - Path to secrets env file (default: config/env/secrets.env)
• --env-output - Path for generated env file (default: <dir>/.central.env)
• --env-context - Value for ENV_CONTEXT (default: central)

---

frameworks services up

Start central services.

frameworks services up
frameworks services up --only commodore,quartermaster
frameworks services up --ssh admin@central-01

Flags:

• --dir - Directory containing generated compose files
• --only - Comma-separated services to start
• --ssh - Run remotely on user@host via SSH
• --ssh-key - SSH private key path

---

frameworks services down

Stop central services.

frameworks services down
frameworks services down --only commodore

Flags:

• --dir - Directory containing generated compose files
• --only - Comma-separated services to stop
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks services status

Show container status for running services.

frameworks services status
frameworks services status --only commodore,bridge

Flags:

• --dir - Directory containing generated compose files
• --only - Comma-separated services to filter
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks services logs

View service logs.

frameworks services logs
frameworks services logs --only commodore --follow --tail 500

Flags:

• --dir - Directory containing generated compose files
• --only - Comma-separated services to filter
• --follow - Follow/tail logs
• --tail - Number of lines to show (default: 200)
• --ssh - Run remotely via SSH
• --ssh-key - SSH private key path

---

frameworks services health

Show aggregated service health from Quartermaster.

# All services
frameworks services health

# Filter by service type
frameworks services health --type commodore

# Filter by specific service ID
frameworks services health --service-id commodore-prod-01

Flags:

• --service-id - Filter by service ID
• --type - Filter by service type (catalog name)

---

frameworks services discover

Query service discovery endpoints.

frameworks services discover --type commodore
frameworks services discover --type foghorn --cluster-id central-production

Flags:

• --type - Service type/catalog name (required)
• --cluster-id - Filter by cluster ID

---

Context Commands

Manage CLI contexts (endpoints, persona, gitops defaults). A context bundles everything the CLI needs to know for one environment: which control-plane endpoints to call, what kind of operator you are (platform / self-hosted / user), and where your cluster manifests live.

Recommended onboarding: run frameworks setup for an interactive wizard that captures all of the above at once. For CI or scripted provisioning, use context create + the context set-* commands below.

frameworks context create

Create a new (empty) context with default localhost endpoints. Does not switch to it — pair with context use <name>.

frameworks context create platform-prod

This is the non-interactive entry point the setup wizard is built on. Use it when you want to bootstrap a context from a script without going through the TTY prompts.

---

frameworks context set-*

Non-interactive setters for the fields the setup wizard captures interactively. Each targets the active context, or --context <name> for a specific one. They error if the target context doesn’t exist — use context create first.

frameworks context set-persona platform --context platform-prod
frameworks context set-gitops-source local --context platform-prod
frameworks context set-gitops-path /path/to/gitops --context platform-prod
frameworks context set-gitops-repo Livepeer-FrameWorks/gitops --context platform-prod
frameworks context set-gitops-ref main --context platform-prod
frameworks context set-gitops-cluster production --context platform-prod
frameworks context set-gitops-manifest clusters/production/cluster.yaml --context platform-prod
frameworks context set-age-key ~/.config/sops/age/keys.txt --context platform-prod

Available setters: set-persona, set-gitops-source, set-gitops-path, set-gitops-repo, set-gitops-ref, set-gitops-cluster, set-gitops-manifest, set-age-key. Plus the existing set-url and set-cluster for endpoints.

---

frameworks context list

List available contexts.

frameworks context list

Sample output:

* local
  production
  staging

---

frameworks context use

Switch to a different context.

frameworks context use production

---

frameworks context show

Show details of a context.

# Show current context
frameworks context show

# Show specific context
frameworks context show production

---

frameworks context set-cluster

Set the active cluster ID for the current context.

frameworks context set-cluster <cluster-id>

This determines which cluster subsequent commands operate against.

---

frameworks context set-url

Update a service endpoint URL.

frameworks context set-url bridge http://bridge.example.com:18000
frameworks context set-url quartermaster-grpc quartermaster.internal:19002 --allow-insecure
frameworks context set-url foghorn-grpc 10.88.0.10:18019 --allow-insecure

Valid service keys: bridge, signalman-ws, commodore-grpc, quartermaster-grpc, purser-grpc, periscope-grpc, signalman-grpc, foghorn-grpc, decklog-grpc, navigator-grpc. Saved non-local gRPC endpoints do not infer transport from hostname or IP shape. Pass --tls for TLS endpoints and --allow-insecure for plaintext endpoints.

---

frameworks context check

Check connectivity to all endpoints in the current context.

frameworks context check

---

Authentication Commands

frameworks login

Authenticate with the FrameWorks platform using your user session token (the same credential the macOS tray uses).

frameworks login

Token storage. The session is written to the platform-native credential store and never appears in shell history:

• macOS: Keychain service com.livepeer.frameworks, account user_session.
• Other platforms: $XDG_DATA_HOME/frameworks/credentials with mode 0600.

For CI/automation, set FW_USER_TOKEN in the environment — it overrides whatever the store holds. Run frameworks config path --kind credentials to print the active backend (e.g. keychain:com.livepeer.frameworks on macOS).

The platform SERVICE_TOKEN is not a user credential. It is loaded from your manifest env_files (gitops) during cluster provision and admin commands. There is no login --service-account.

frameworks logout

Clear the stored user session.

frameworks logout

Deletes both user_session and refresh_token so a running tray can’t silently repopulate them. The gitops-sourced SERVICE_TOKEN is unaffected — logout does not touch platform configuration.

---

Utility Commands

frameworks setup

Run the interactive onboarding wizard. It captures the operator persona, Bridge endpoint, and platform GitOps manifest defaults into a CLI context, then makes that context current. Self-hosted/BYO edge setup uses Bridge and does not ask for Quartermaster or Foghorn gRPC addresses.

frameworks setup

For non-interactive setup, use frameworks context create <name> followed by the relevant frameworks context set-* commands.

---

frameworks update

Update the CLI to the latest version.

# Update to latest
frameworks update

# Check for updates without installing
frameworks update --check

Flags:

• --check - Only check for updates, don’t install

Downloads the latest release from GitHub, verifies the checksum, and atomically replaces the running binary. If the binary is installed in a directory requiring elevated permissions, use sudo frameworks update.

---

frameworks version

Print CLI and platform version info.

frameworks version

---

frameworks menu

Launch interactive menu for common operations.

frameworks menu

Provides a guided interface for:

• Edge Operations
• Services & Health
• Control / API Plane (Admin)
• Cluster Operations
• DNS & Mesh
• Settings & Contexts

---

frameworks config env

Generate a merged .env file from layered configuration.

# Generate .env in current directory
frameworks config env

# Custom base and secrets files
frameworks config env --base config/env/base.env --secrets config/env/secrets.env

# Output to stdout
frameworks config env --output -

# Specify context
frameworks config env --context production

Flags:

• --base - Path to base env file (default: config/env/base.env)
• --secrets - Path to secrets env file (default: config/env/secrets.env)
• --output - Output path (default: .env, use - for stdout)
• --context - Value for ENV_CONTEXT (default: dev)

---

Additional Config Commands

Command	Purpose
frameworks config set <key> <value>	Store GitHub App settings used for GitHub-sourced manifests.
frameworks config get <key>	Print a stored GitHub App setting.
frameworks config path	Print the canonical config path or credential-store location. Supports --kind config|credentials.

Supported config set/get keys are github.app-id, github.installation-id, github.private-key, github.repo, and github.ref.

frameworks config set github.repo org/gitops
frameworks config get github.repo
frameworks config path --kind credentials

---

Exit Codes

• 0 - Success
• 1 - General error
• 2 - Invalid arguments
• 3 - Service not found
• 4 - Connection error
• 5 - Health check failed