Ferqon CLI Reference — Ferqon Docs

Ferqon CLI Reference

Moved from AGENTS.md to reduce per-session token overhead. Read this file when you need detailed CLI commands, configuration keys, environment profiles, or install/uninstall procedures.

What's in each CLI

ferqon (production — ferqon-cli-core):

auth, config, devices, sessions, diagnostics, admin, teams, iot, flash
jobs, rigs, orchestration, users, audit, updates
server start / stop / restart / status / logs / version / paths / reload / deploy
server config / server maintenance

ferqon-dev (developer — ferqon-cli-dev, extends ferqon):

Everything in ferqon plus:
test group — run tests (simulated, real, hardware, backend)
dev group — reset-db, restart-frontend, open-browser
server doctor — check system dependencies
server bootstrap — first-time developer setup
server dev-env — display dev environment configuration
server start-docker / stop-docker / logs-docker — Docker Compose dev stack
server start-source — start backend from source (uvicorn via run_server.py, no PyInstaller)

Development Environment

The make dev-start command sets up a development environment where:

Editable CLI installation: Both ferqon-cli-core and ferqon-cli-dev are installed in editable mode into services/backend/.venv, so any changes to packages/ferqon-cli/ or packages/ferqon-cli-dev/ take effect immediately without reinstalling.
Configured shell: A subshell is spawned with:
- PATH updated to prioritize the backend venv (so ferqon and ferqon-dev resolve to the editable copies)
- FERQON_REPO_ROOT set to the repository root
- FERQON_SERVER_URL set to http://localhost:8001 (dev backend)
- FERQON_DEPLOYMENT_MODE=dev (explicit development mode)
- FERQON_DEV_ENV=1 marker
- Prompt marked with (ferqon) to indicate the dev environment
CLI configuration: The CLI reads configuration from ~/.config/ferqon/config.yml. Dev-specific settings are under the dev.* namespace.

Server Management

Customer-visible commands (ferqon — always fail-secure, no flags needed):

ferqon server start — Start standalone ferqon_server binary (fail-secure: HTTPS, license, signed firmware)
ferqon server start --detach — Start in background
ferqon server stop — Stop standalone binary
ferqon server restart — Restart standalone binary
ferqon server status — Show standalone binary status (PID + health)
ferqon server logs — Stream standalone binary log file
ferqon server deploy <release-dir> — Atomic symlink swap + restart with auto-rollback
ferqon server version — Show server version and capabilities
ferqon server paths — Display runtime path resolution
ferqon server reload — Reload server configuration (admin only)
ferqon server config get/set — Server configuration management (admin only)
ferqon server maintenance enable/disable/status — Maintenance mode management
ferqon completion <shell> — Generate shell completion script (bash/zsh/fish)
ferqon database info — Show database path, size, and encryption status
ferqon database encrypt — Enable SQLCipher encryption (interactive confirmation)
ferqon database decrypt — Disable SQLCipher encryption (interactive confirmation)
ferqon updates check/upgrade/rollback/create-snapshot — Package update and rollback

Dev-only commands (ferqon-dev — requires make dev-start):

ferqon-dev server start-docker — Start Docker Compose dev stack
ferqon-dev server stop-docker — Stop Docker Compose dev stack
ferqon-dev server logs-docker — Stream Docker Compose logs
ferqon-dev server start-source — Start backend from source (uvicorn via run_server.py, no PyInstaller)
ferqon-dev server doctor — Check system dependencies
ferqon-dev server bootstrap — First-time developer setup
ferqon-dev server dev-env — Display dev environment configuration
ferqon-dev dev reset-db — Reset the development database
ferqon-dev dev restart-frontend — Restart the Vite dev server
ferqon-dev dev open-browser — Open the frontend in a browser
ferqon-dev test — Run tests (simulated, real, hardware, backend)

Flash

Flash firmware to a connected device and manage flash jobs.

ferqon flash <firmware>                        # default: upload + flash
ferqon flash -d /dev/ttyACM0 <firmware>        # explicit device
ferqon flash <firmware> --family esp32 --board esp32-s3 --offset 0x1000
ferqon flash --device COM3 --upload-id <id>   # use pre-uploaded firmware
ferqon flash status [job_id]                   # show job status
ferqon flash logs [job_id]                     # show logs
ferqon flash list                              # list all jobs
ferqon flash cancel <job_id>                   # cancel a job
ferqon flash profiles [search-term]            # board profile lookup
ferqon flash upload <firmware> --role single    # upload firmware and return id

Configuration

ferqon config get <key> — Get a configuration value
ferqon config set <key> <value> — Set a configuration value
ferqon config paths — Display runtime path hints

Dev-specific configuration keys:

dev.data_dir — Data directory for the backend (default: .ferqon-dev/data)
dev.backend_port — Backend port (default: 8001)
dev.frontend_port — Frontend port (default: 5178)
dev.skip_bootstrap — Skip bootstrap code (default: 1)

Production-specific configuration keys:

prod.host — Bind address (default: 127.0.0.1)
prod.port — Listen port (default: 8000)
prod.data_dir — Data directory (default: ~/.ferqon_server/data)
prod.license_path — License file path (default: ~/.ferqon_server/license.ferqon)
prod.server_binary_path — Override ferqon_server binary path (default: auto-detect /opt/ferqon/bin/ferqon_server → ~/.local/ferqon/bin/ferqon_server)

Example:

ferqon config set dev.data_dir /tmp/ferqon-altdata
ferqon server restart

# Production: configure host/port for customer deployment
ferqon config set prod.host 0.0.0.0
ferqon config set prod.port 8443
ferqon server start

Environment Profiles

Ferqon uses a unified profile system to keep dev/test/prod/staging env vars in one place. Profiles are stored in the monorepo at ops/profiles/ and are sourced by the Makefile before build/run commands. Only *.env.example templates are committed; real .env files are gitignored.

| Profile | Purpose | | --- | --- | | dev | Local development on localhost (skip license, hot reload) | | lan-test | LAN testing with a local website instance (real license, HTTP allowed) | | staging | staging.revyrlabs.com, fail-secure | | prod | revyrlabs.com, fail-secure |

Key env vars:

FERQON_VENDOR_URL — canonical single source of truth for the Revyr Labs website URL. Read at build time (baked into the binary) and at runtime as the fallback.
FERQON_LICENSE_VENDOR_URL — runtime override for LAN testing; no rebuild required.
Legacy aliases (FERQON_WEBSITE_URL, FERQON_ACTIVATION_BASE_URL, FERQON_LICENSE_VENDOR_HOST/PORT/USE_TLS) still work.

Shared secrets (especially FERQON_SERVER_HMAC_SECRET) are kept in sync with the revyrlabs_website via scripts/sync-shared-secrets.sh in the superrepo.

Usage

# Copy a template and fill in secrets
cp ops/profiles/prod.env.example ops/profiles/prod.env

# Build or run with a profile
make build PROFILE=prod
make dev PROFILE=dev
make prod PROFILE=prod

# Inspect/validate the environment
ferqon-dev env show
ferqon-dev env validate

See ../docs/env-profile-system.md in the monorepo for the full design.

Production Build & Test

Ferqon has two production deployment paths:

Standalone Binary (customer, default)

Builds the ferqon_server PyInstaller binary and launches it via the CLI. This is the default make prod path — the customer-facing workflow that requires no Docker or repo checkout at runtime.

make prod                    # Build binary + launch via CLI (default)
make prod-deploy             # Build + install + start (full customer deploy from source)

# Day-to-day server lifecycle — use the ferqon CLI directly:
ferqon server start --detach # Start the server in background
ferqon server stop           # Stop the server
ferqon server restart        # Restart the server
ferqon server status         # Show server status (PID + health)
ferqon server logs -f        # Stream server logs

The binary self-configures all runtime secrets on first boot.

Install / Uninstall

Customer workflow — no make, no repo checkout, no build tools needed:

The release folder ships with ferqon_install.sh, ferqon_uninstall.sh, ferqon_cli, and ferqon_server. Customers just run:

sudo ./ferqon_install.sh             # Install CLI + server to /opt/ferqon/
ferqon server start           # Start the server
sudo ./ferqon_uninstall.sh           # Remove everything
sudo ./ferqon_uninstall.sh --purge   # Also remove ~/.ferqon_server/ (data, license, logs)

After install, ferqon is at /usr/local/bin/ferqon (symlink to /opt/ferqon/bin/ferqon). The ferqon_server binary is at /opt/ferqon/bin/ferqon_server.

Developer workflow — make targets that build + assemble the release folder, then install from it:

make release                  # Build binaries + copy install scripts → dist/release/
make install                  # release + sudo ./ferqon_install.sh (dev shortcut)
make uninstall                # sudo ./ferqon_uninstall.sh
make uninstall PURGE=1        # Also remove ~/.ferqon_server/ (data, license, logs)

The CLI finds the server binary automatically by checking:

ferqon config set prod.server_binary_path <path> — explicit override
/opt/ferqon/bin/ferqon_server — default install location
~/.local/ferqon/bin/ferqon_server — user-level fallback

Docker Compose (ops/dev)

Builds the backend Docker image and starts the full compose stack (backend + MQTT + IoT agent + monitoring). Used for ops, self-hosted deployments, and development that needs the full stack. Requires ferqon-cli-dev to be installed (make dev-start).

make prod-docker             # Build image + start compose stack
make prod-start-docker       # Start without rebuilding
make prod-stop-docker        # Stop compose stack
make prod-logs-docker        # Stream compose logs

Default shortcuts

make prod and make prod-deploy default to the standalone binary path (the customer-facing default). Use the explicit -docker variants when you need the Docker Compose stack. For day-to-day server lifecycle (start, stop, restart, status, logs), use the ferqon server CLI commands directly.

CI verification

release.yml builds the standalone binary via ferqon_server.spec (same as make build) so CI and local builds produce identical binaries.
prod-smoke.yml builds the standalone binary and runs a production smoke test (health + version + API) against it on every push that affects the binary or CLI.
smoke-integration.yml runs the Docker Compose stack smoke test.