⌨️ CLI reference
The complete surface of the nocloud command. Every subcommand that produces structured output
accepts --json for automation. The installation lives at NOCLOUD_HOME (default ~/nocloud,
remembered in ~/.config/nocloud/home).
Install & configure
| Command | What it does |
|---|---|
nocloud init [dir] |
installs the product: clones the repo, creates .venv, installs dependencies, initializes and seeds the database |
nocloud setup |
guided assistant: detects your network (your IP, router, and reachable home-server candidates) and writes config/site.env; keeps any previous file as site.env.bak |
nocloud config list\|check\|get <key>\|set <key> <value>\|export |
instance configuration, validated against config/schema.yaml; secrets are masked in output; set backs up site.env first |
nocloud update |
git pull --ff-only, dependency refresh, and macOS Agent rebuild/restart when main changed |
nocloud auth [--json] |
validates the public protected-route → login handoff and login UI without using credentials |
nocloud jobs run check_updates |
git fetch + compares the VERSION file against origin, without pulling — a real release, not just new commits, is what feeds the "update available" banner at the top of every page (see Installation); also checks the companion nocloud-store checkout the same way nocloud update already does, if one exists. Doesn't run on a schedule by default |
nocloud version |
installed version |
nocloud home |
prints where the installation lives |
Data & publishing
| Command | What it does |
|---|---|
nocloud onboard <path> |
ingests a folder of photos/videos or a recognized export (WhatsApp, Google Takeout), reversibly, then runs build |
nocloud demo |
builds and serves a real dashboard with made-up data on a free local port (opens your browser there) — no home server, Immich, or account needed; nothing of yours is touched |
nocloud build |
generates every page and the API into build/site (never touches the server) |
nocloud deploy |
build + publish to the server over SSH (needs config/site.env) |
nocloud test |
smoke test with synthetic data — never touches real data |
Operate
| Command | What it does |
|---|---|
nocloud doctor [--json] |
17 installation checks; exits non-zero if any fails |
nocloud auth [--json] |
verifies the public login handoff before deployment; see Signing in |
nocloud journey [--json] |
shows the next foundation action, optional app journeys and recovery attention across the private home |
nocloud jobs list\|status\|run <id>\|history [id] [--json] |
the job registry (config/jobs.yaml) |
nocloud events [--limit N] [--json] |
latest platform events |
nocloud audit summary\|list\|check\|export\|emit <kind> <msg> [--severity] [--owner] [--data-json] [--json] |
the audit event stream |
nocloud upgrade plan\|preflight\|run\|status\|rollback [--json] |
the upgrade lifecycle; run is plan-only unless --execute, also accepts --deploy (deploy is skipped otherwise) and --allow-dirty |
nocloud module list\|doctor\|install <slug>\|remove <slug>\|registry [--write] |
the module SDK |
nocloud backup [--json] |
validates the backup contract (config/backup_manifest.yaml) AND the destination: fails unless a fresh snapshot with an intact DB copy exists at BACKUP_DEST |
nocloud restore [source] [--execute] [--json] |
restores backup manifest items from source (default: BACKUP_DEST/backups/latest); plan-only unless --execute |
nocloud legacy |
generates build/legacy/envelope.html: one printable, self-contained page for an heir — what this system is, where the three directories live, how to reach and restore it; contains no secrets, see Recovery |
nocloud freeze --out PATH |
exports the whole archive (family tree, provenance, finances, every app page — not the photo/video library, see Recovery) to a self-contained, offline directory that opens in any browser with python3 start_archive.py, no server required |
nocloud integrations list\|status\|check\|actions <id> [--json] |
third-party adapters (Immich, Home Assistant, docker, systemd, launchd, syncthing, mail, CasaOS); list/status/check are aliases |
nocloud security |
refreshes catalog/api/security.json from the server over SSH |
nocloud daemon [--host H] [--port P] |
starts the local runtime API (below) |
nocloud daemon
Serves the platform's state on 127.0.0.1:8765 by default (configure with --host/--port, the
NOCLOUD_DAEMON_HOST/NOCLOUD_DAEMON_PORT variables, or daemon_port in
config/runtime.yaml).
| Endpoint | Content |
|---|---|
GET /api |
index of every endpoint |
GET /api/health |
daemon liveness |
GET /api/jobs, /api/jobs/<id>, /api/jobs/history, /api/jobs/<id>/history |
job registry and run history |
POST /api/jobs/<id>/run |
trigger a job on demand (what "↻ Refresh" buttons call) |
GET /api/events, /api/audit |
platform events and audit stream |
GET /api/upgrade, /api/integrations, /api/platform, /api/config |
upgrade status, adapters, the combined platform dashboard (checks, jobs, config, audit, modules, backup, events), daemon runtime paths and binding |
Set NOCLOUD_DAEMON_TOKEN to require Authorization: Bearer <token> on every request;
NOCLOUD_DAEMON_CORS_ORIGIN restricts browser callers.
Environment knobs
These override defaults when set in the shell that runs nocloud:
| Variable | Effect |
|---|---|
NOCLOUD_HOME |
where the installation lives (else ~/.config/nocloud/home, else ~/nocloud) |
NOCLOUD_REPO_URL |
repo cloned by nocloud init |
NOCLOUD_STORE_DIR |
where the companion nocloud-store checkout lives (default: next to the core checkout) |
NOCLOUD_DB |
path of the SQLite catalog (default local/db/nocloud.sqlite) |
NOCLOUD_STATE_DIR |
where job locks/history live (default ~/.local/state/nocloud) |
NOCLOUD_DAEMON_HOST / NOCLOUD_DAEMON_PORT / NOCLOUD_DAEMON_TOKEN / NOCLOUD_DAEMON_CORS_ORIGIN |
daemon binding, auth and CORS |
Instance configuration (hosts, URLs, keys, paths) does not go in the shell — it lives in
config/site.env; see the configuration reference.