A fast reference for the ferqon command-line interface and the shell
scripts shipped alongside it. Covers installation, the dev workflow, the
production self-host workflow, and every command group.
Source of truth: command definitions live in
packages/ferqon-cli/ferqon_cli/commands/*.py. This guide mirrors the commands actually registered inmain.py. If a command here doesn't match the code, the code wins — please update this file.
Recommended for Ferqon developers:
cd Ferqon
make dev-start # installs editable ferqon + ferqon-dev, opens a configured shell
ferqon --version
Or, manually install only the production CLI package:
cd Ferqon/packages/ferqon-cli
pip install -e .
ferqon --version
The release folder ships with ferqon_install.sh, ferqon_uninstall.sh, ferqon_cli,
and ferqon_server. No make or build tools required.
| Script | When to use |
|--------|-------------|
| ferqon_install.sh | Install ferqon CLI + ferqon_server binary to /opt/ferqon/. Requires sudo. |
| ferqon_uninstall.sh | Remove everything installed by ferqon_install.sh. Use --purge to also remove data. |
# 1. Install
sudo ./ferqon_install.sh
# 2. Verify
ferqon --version
# 3. Start the server
ferqon server start
# Later: uninstall
sudo ./ferqon_uninstall.sh
# Or purge (removes binaries + data + license + logs)
sudo ./ferqon_uninstall.sh --purge
source <(ferqon completion bash) # bash
source <(ferqon completion zsh) # zsh
ferqon completion fish | source # fish
The CLI searches config in this order (first wins):
--config flag$FERQON_CONFIG env var./.ferqon/config (project-local)~/.config/ferqon/config.yml (user-global)/etc/ferqon/config.yml (system-wide)ferqon config get # show all
ferqon config get server.url # one key
ferqon config set server.url http://localhost:8001
ferqon config set output.format table
ferqon config set output.color auto
ferqon config paths # runtime path hints
Dev-only keys (used by ferqon server):
| Key | Default | Purpose |
|-----|---------|---------|
| dev.data_dir | .ferqon-dev/data | Backend data directory (bind-mounted) |
| dev.backend_port | 8001 | Backend port |
| dev.frontend_port | 5178 | Frontend port |
| dev.skip_bootstrap | 1 | Skip bootstrap code |
ferqon config set dev.backend_port 8002
ferqon server restart
The canonical dev loop uses the CLI inside a configured subshell. The dev CLI
adds ferqon-dev with Docker Compose and test commands.
# From the Ferqon repo root
make dev-start # editable CLI + (ferqon) subshell
# Inside the (ferqon) shell:
ferqon-dev server start-docker --build # Docker backend + frontend + MQTT/IoT
ferqon server status # health check (talks to the API)
ferqon-dev server logs-docker # stream Docker compose logs
ferqon-dev server stop-docker # stop the stack
exit # leave the dev shell
The make dev-start shell sets PATH, FERQON_REPO_ROOT,
FERQON_SERVER_URL=http://localhost:8001, FERQON_DEPLOYMENT_MODE=dev,
and FERQON_DEV_ENV=1, and marks the prompt with (ferqon).
make dev-source # fastest: backend + frontend from source, no Docker
make dev-source-down # stop the source dev stack
make dev-fast-min # backend + MQTT + IoT + frontend watch, no CLI
make dev-fast # same + Ferqon Studio desktop window
make dev-fast-down # stop everything
make dev-fast-restart # restart Docker services
make dev # backend-only hot-reload on :8000 (no Docker)
ferqon server (standalone binary)ferqon setup # first-run configuration (vendor + server URLs)
ferqon server start # launch standalone ferqon_server binary
ferqon server status # process + API health
ferqon server logs -f # tail logs
ferqon server restart # restart the binary
ferqon server stop # stop the binary
ferqon server version # server + CLI version
ferqon server paths # resolved runtime paths
ferqon server reload # hot-reload backend config
ferqon updates upgrade # pull + apply a new release
ferqon server start supports:
--detach — run in background--no-health-check — skip post-start health checkferqon updates supports:
check — preview available updateupgrade — download and apply update with pre-update backuprollback — roll back to the previous versionFor air-gapped / packaged deployments, use the scripts in
packages/enterprise/runtime/ (installed by install_service.sh):
sudo ./install_service.sh # one-time: installs systemd unit
sudo systemctl start ferqon-ee # start the stack
sudo systemctl status ferqon-ee # systemd status
ferqon-ee-status # docker compose ps
ferqon-ee-logs # docker compose logs -f
sudo systemctl stop ferqon-ee # stop
install_service.sh installs ferqon-ee-start / -stop / -status /
-logs into /usr/local/bin and a ferqon-ee.service systemd unit
(enabled at boot). start.sh loads the bundled image tar, runs
docker compose --env-file .env up --detach, and waits for the backend
container to reach running state.
sudo tools/dev/ops/install_linux.sh \
--repo-dir /opt/ferqon --start --guided-setup
Installs a /usr/local/bin/ferqon wrapper and ferqon.service, then
optionally runs interactive ferqon setup as the invoking user.
ferqon maintenance enable "Deploying v1.2.3"
ferqon maintenance status
ferqon maintenance disable
Command groups registered in main.py. Groups behind a disabled feature
flag are hidden at runtime (see FEATURE_COMMANDS in
ferqon_cli/main.py).
auth — authenticationferqon auth login [--username U --password P | --with-token TOKEN] [--server-url URL]
ferqon auth logout
ferqon auth status
ferqon auth whoami
ferqon auth refresh
ferqon auth token [--name NAME] [--expires 1d]
setup — first-run configurationferqon setup # interactive prompts (auto-detects server URL)
ferqon setup --non-interactive --server-url http://localhost:8000
server — standalone server lifecycleSee §4.
ferqon server start [--detach] [--no-health-check]
ferqon server stop
ferqon server restart
ferqon server status
ferqon server logs [-f] [-n N] [--pretty] [--log-file PATH]
ferqon server version
ferqon server paths
ferqon server reload [--force]
ferqon server config get|set <key> [value]
ferqon server maintenance enable|disable|status [message]
ferqon server deploy <release-dir>
dev / test — developer-only commands (ferqon-dev)These commands require ferqon-cli-dev (installed via make dev-start).
ferqon-dev dev reset-db # wipe dev database
ferqon-dev dev restart-frontend # restart the Vite dev server
ferqon-dev dev open-browser # open the frontend in a browser
ferqon-dev server doctor # environment + dependency diagnostics
ferqon-dev server bootstrap # first-time developer setup
ferqon-dev server dev-env # display dev environment configuration
ferqon-dev server start-docker [--build] [--detach] [--no-health-check]
ferqon-dev server stop-docker
ferqon-dev server logs-docker [--follow] [--service SERVICE]
ferqon-dev test list [--type backend|hardware|...] [--json]
ferqon-dev test run <folder> [--filename F] [--type T] [-v] [--debug] [--parallel N] [--filter-name PATTERN]
ferqon-dev test watch <folder> [--interval S] [--filter-name PATTERN]
ferqon-dev test debug <folder>
config — configurationSee §2.
device — connected devicesferqon devices list [--known-only] [--limit N]
ferqon devices scan
ferqon devices show <port>
ferqon devices claim <port> [--force]
ferqon devices release <port> [--force]
ferqon devices watch [--follow]
session — HIL / serial sessionsferqon sessions list [--all] [--user U | --device D] [--limit N]
ferqon sessions show <id>
ferqon sessions end <id>
diag — diagnosticsferqon diagnostics ping [--count N] [--timeout MS]
ferqon diagnostics health
ferqon diagnostics doctor [--output-file report.json]
ferqon diagnostics trace <request-id>
ferqon diagnostics metrics
ferqon diagnostics bundle [--output-file bundle.tar.gz]
admin — site administrationferqon admin admins list | add <github_id> <login> | remove <github_id>
ferqon admin test-users list | grant <github_id> <login> | revoke <github_id>
ferqon admin roles list | grant <github_id> <role> | revoke <github_id> <role>
ferqon admin jwt info | rotate
team — teams (teams feature)ferqon teams list | show <id> | create <name> | rename <id> <name> | delete <id>
ferqon teams join <code> | leave <id>
ferqon teams members list|add|remove|promote <team_id> ...
ferqon teams devices list|assign|unassign <team_id> ...
ferqon teams transfer list|create|approve|reject|cancel ...
iot — IoT / MQTT (iot feature)ferqon iot devices list|show|create|delete|enable|disable|token-rotate ...
ferqon iot tags list|add|remove --device <device_id> <tag>
ferqon iot telemetry list [--device D] [--limit N]
ferqon iot commands list|send ...
ferqon iot routes list|all|add|remove|reload
ferqon iot settings show|update ...
ferqon iot ca-cert [--format pem|json] [--output-file PATH]
flash — firmware flashing (ota_http feature)# Default action: flash a firmware file to the auto-detected device
ferqon flash <firmware>
ferqon flash -d /dev/ttyACM0 <firmware>
ferqon flash --device COM3 <firmware>
ferqon flash <firmware> --family rp2040 --board Pico --offset 0x10000000
# Job lifecycle
ferqon flash status [job_id]
ferqon flash logs [job_id]
ferqon flash list [--limit N] [--status S]
ferqon flash cancel <job_id>
# Helpers
ferqon flash profiles [search-term]
ferqon flash upload <firmware> [--family F] [--board B] [--role R]
jobs / rigs — control plane (automations feature)ferqon rigs list|get|cordon|uncordon|label ...
ferqon jobs submit|list|get|logs|cancel ...
ferqon orchestration leases list|release|renew ...
ferqon orchestration safety kill|policy-list|policy-add ...
ferqon orchestration observability metrics|audit|status
users — user managementferqon users list [--limit N] [--offset N]
ferqon users create [--username USERNAME] [--email EMAIL] [--password <password>] --role R [--force]
ferqon users delete <user_id> [--force]
ferqon users reset-password <user_id> --password <password>
audit — audit logferqon audit search [QUERY] [--action A] [--actor A] [--from DATE] [--to DATE] [--limit N] [--format {table,json,csv}] [--output FILE]
ferqon audit log [--limit N]
update — release updatesferqon updates check [--component cli] [--component server]
ferqon updates upgrade [--dry-run]
ferqon updates rollback [--list] [--to BACKUP_DIR]
Some command groups are hidden when their feature flag is disabled. The
CLI queries /api/system/features and falls back to FERQON_FEATURE_*
env vars.
| Feature flag | Hidden groups when disabled |
|--------------|------------------------------|
| iot | iot |
| ota_http | flash |
| automations | orchestration |
| lab | lab |
| teams | team |
| cameras | (no CLI commands yet) |
Force-enable for local testing:
FERQON_FEATURE_IOT=1 ferqon iot devices list
Beyond the CLI, these scripts are commonly used for server setup and operations. Paths are relative to the Ferqon repo root.
tools/dev/ops/| Script | Purpose |
|--------|---------|
| ferqonctl.sh | Control script: runtime env, HTTPS URLs, runtime links JSON. |
| start_ferqon.sh / start_ferqon_safe.sh / start_production.sh | Start the stack (safe/production variants). |
| stop_ferqon.sh | Stop the stack. |
| run_ferqon.sh | Run the backend with runtime env. |
| install_linux.sh | systemd installer (see §4 Option C). |
| install.sh / install_local_dev.sh | Local dev installers. |
| uninstall_linux.sh | Remove the systemd unit + wrapper. |
| setup_https.sh | Provision TLS certs. |
| pre_startup.sh | Pre-flight checks before startup. |
| run_all_diagnostics.sh | Run every diagnostic. |
| free_port_9000.sh | Free a stuck port. |
| trust_mkcert_ca.sh | Trust the local mkcert CA. |
| generate-portable-env.sh | Generate a portable env bundle. |
| validate-deps.sh / lint-naming.sh / shellcheck.sh | Validation/lint helpers. |
packages/enterprise/runtime/| Script | Purpose |
|--------|---------|
| install_service.sh | Install systemd unit + wrappers (see §4 Option B). |
| start.sh / stop.sh / status.sh / logs.sh | Stack lifecycle via docker compose. |
infra/iot/mqtt/| Script | Purpose |
|--------|---------|
| certs/generate_dev_certs.sh | Generate dev MQTT certs. |
| config/start-mosquitto.sh | Start the Mosquitto broker. |
ferqon not found after install — the installer creates a symlink at
/usr/local/bin/ferqon. Ensure /usr/local/bin is on your PATH. If the
symlink is missing, re-run sudo ./ferqon_install.sh.
CLI not picking up repo changes — you must be inside the
make dev-start shell (prompt shows (ferqon)). Outside it, the global
install is used.
Production data not persisting — check ferqon server paths; ensure
prod.data_dir points to a writable directory.
Port conflicts — change ports via config and restart:
# Production standalone binary
ferqon config set prod.port 8443
ferqon server restart
# Dev Docker stack
ferqon config set dev.backend_port 8002
ferqon config set dev.frontend_port 5179
ferqon-dev server start-docker
Frontend not starting (dev) — tail -f .ferqon-dev/frontend.log and run
make setup-frontend if deps are missing.
Run full diagnostics:
ferqon diagnostics doctor
ferqon-dev server doctor
tools/dev/ops/run_all_diagnostics.sh
packages/ferqon-cli/README.md — install + config overviewFerqon/AGENTS.md — dev workflow and architectureFerqon/FEATURES.md — UI/route feature inventoryFerqon/docs/archive/cli.md — CLI ↔ API mappingFerqon/Makefile — make target reference (make help)