Operations

Use the CLI as the control plane for a managed /opt/argus VPS. It inspects before every mutation, applies the inspected plan, then verifies the result. Do not edit compose.yaml, state.json, release-context.json, managed SearXNG settings, or update state by hand.

Run argus in a terminal for the guided menu. The direct commands below are useful when you know the operation already or are writing automation.

Safety flags and output

--dry-run is available on mutating commands and prints the plan without changing the instance. --yes accepts the current inspected plan without an interactive confirmation. In non-interactive or --json use, a mutation without --yes fails with CONFIRMATION_REQUIRED; inspect with --dry-run first. Declining the interactive confirmation exits with CONFIRMATION_DECLINED and changes nothing.

--json emits the versioned command boundary for scripts and agents: successful responses contain contractVersion, ok, and data; failures contain contractVersion, ok, and an error with a stable code, message, and any recovery guidance. Without it, output is formatted for people. status, logs, and doctor inspect only and do not accept --dry-run or --yes.

Lifecycle

Start, stop, and restart first inspect the selected Compose services, validate the rendered Compose configuration, make the change, then verify the desired services are stopped or healthy and running.

# Inspect, then start.
argus start --dry-run --json
argus start --yes --json

# Inspect, then stop or restart.
argus stop --dry-run --json
argus stop --yes --json
argus restart --dry-run --json
argus restart --yes --json

# Non-mutating state and bounded logs.
argus status
argus logs --tail 200
argus logs argus --tail 200
argus logs --raw
argus doctor

status --json returns { state: "running" | "degraded", services: { ... } }. state is running only when every selected service is running and not unhealthy; otherwise it is degraded. Each service value is Docker health when present, otherwise Docker state. The human summary uses the same public state and service values. Human logs removes container prefixes and noisy runtime metadata; use logs --raw for exact bounded Docker Compose output. logs accepts argus, postgres, searxng, or fxembed; its tail must be a positive integer no larger than 10,000 and is time-bounded. An invalid tail is LOG_TAIL_INVALID; an unsupported service is LOG_SERVICE_INVALID.

doctor runs independent bounded checks for Docker, the authenticated Argus API, selected storage, SearXNG, FxEmbed, and enabled source smoke targets. A check is healthy, unhealthy, or skipped; the complete report is healthy only when no check is unhealthy. It supplies an error code, bounded log command, and recovery text when available. Source smoke checks create an isolated temporary diagnostic watch, poll it within a deadline, then remove it; they do not use or alter normal watch records.

Configuration and secrets

Validate an intended YAML document before asking the live service to inspect, apply, and verify it. Applying an installed configuration requires the authenticated local management integration, and the service rejects a stale plan with CONFIG_SERVICE_PLAN_STALE or a failed verification with CONFIG_APPLY_VERIFY_FAILED.

argus config validate /opt/argus/argus.yaml
argus config show /opt/argus/argus.yaml
argus config export --json
argus config apply --dry-run
argus config apply

Without a path, config apply uses /opt/argus/argus.yaml; pass an explicit path when inspecting another file. Human config show prints redacted YAML; --json returns the structured object. It structurally redacts API tokens, intelligence keys, and URL credentials in both modes. Configuration uses complete ${NAME} references, while values live in the owner-only secrets file. Set one secret through a hidden prompt; the value is never a command argument:

argus secrets set ARGUS_API_TOKEN --dry-run --json
argus secrets set ARGUS_API_TOKEN --yes --json

The name must be an uppercase secret-like environment name or the command returns SECRET_NAME_INVALID. Secret values may not contain line breaks (SECRET_VALUE_INVALID). Argus writes /opt/argus/secrets.env atomically with mode 0600, verifies the stored value, and refuses an unsafe, non-regular, non-owner-owned, or symlinked file with SECRETS_FILE_UNSAFE.

Targeted repair

Repair is limited to managed argus, postgres, searxng, and VPS-hosted fxembed; any other name returns REPAIR_SERVICE_INVALID. Inspect the exact service before a mutation, then verify it through the doctor report:

argus repair argus --dry-run --json
argus repair argus --yes --json

argus repair postgres --dry-run --json
argus repair postgres --yes --json

argus repair searxng --dry-run --json
argus repair searxng --yes --json

argus repair fxembed --dry-run --json
argus repair fxembed --yes --json

PostgreSQL repair is unavailable on a SQLite deployment (POSTGRES_NOT_SELECTED). SearXNG repair is unavailable for disabled or external SearXNG (SEARXNG_NOT_MANAGED). FxEmbed repair is unavailable unless it is VPS-managed (FXEMBED_NOT_VPS_MANAGED). Managed SearXNG repair rewrites only its owned settings; VPS FxEmbed repair restarts only that service. A repair that cannot end with a healthy report returns REPAIR_VERIFY_FAILED. There is no CLI repair for external services or Cloudflare account configuration.

Update and rollback

An update is available only through a signed-release CLI composition. It fetches the stable release manifest and the persisted release context, verifies both, and plans the exact selected services. Review that plan before applying it:

argus update --dry-run --json
argus update --yes --json
argus status --json
argus doctor --json

For a non-noop SQLite plan, Argus proves the Compose-owned argus_argus-data volume, stops the writer, and creates a consistent snapshot under /opt/argus/backups. It quick-checks and hashes that snapshot and records its byte length, table counts, and exact volume identity before pulling pinned images or running migrations. It then starts Compose, checks selected service health, records the new verified state, and advances /opt/argus/management.state to the matching signed management CLI image. The root-owned /usr/local/bin/argus launcher remains immutable. An already-current release is a no-op plan but still performs health verification and can repair stale valid management state from the verified release. A missing state fails closed and requires the signed installer. The CLI does not automatically roll back a failed update; preserve the snapshot, inspect diagnostics, and choose rollback deliberately.

Do not edit management.state: missing or malformed state fails closed before Docker runs. Rerun the signed installer to repair this launcher/state pair. The next release refuses legacy version-pinned launchers instead of upgrading them; remove an obsolete launcher explicitly before installing it.

argus update --rollback --dry-run --json
argus update --rollback --yes --json
argus status --json
argus doctor --json

Rollback requires the persisted verified snapshot and an exactly matching, compatible signed rollback release. For SQLite it revalidates the snapshot before stopping Argus, proves the named volume again, stages the prior database inside that volume, atomically selects it, starts the prior pinned services, verifies health, and restores state.json. UPDATE_ROLLBACK_UNAVAILABLE means required rollback support or recovery material is unavailable: this CLI integration does not support rollback, no verified rollback release is selected, the signed release context or persisted update state is missing, unreadable, or invalid, or a persisted recovery path escapes the instance root. UPDATE_ROLLBACK_INCOMPATIBLE means readable persisted update state has no backup, or its recorded backup/release pairing fails the required schema, manifest, or version metadata. Do not delete /opt/argus/backups, update-state.json, or release-context.json until recovery is complete.

Back up and restore

The managed Compose SQLite database is argus_argus-data; confirm it with read-only Docker commands:

cd /opt/argus
docker compose -p argus config --volumes
docker volume inspect argus_argus-data

Signed updates create and verify their own rollback snapshot of that volume, but retain an independently tested operator-managed Docker-volume backup for disaster recovery. Test operator recovery against a separate volume or staging instance. After any recovery, inspect the managed deployment with argus status --json and argus doctor --json. For PostgreSQL, use pg_dump/pg_restore or provider snapshots outside /opt/argus; after a restore, start each required role and verify its health. Argus does not create or restore PostgreSQL dumps.

Escalation sequence

When a command fails, retain the stable error code and start with these read-only diagnostics:

argus status --json
argus doctor --json
argus logs --tail 200 --json

Use only the service-specific recovery the doctor report names. If rollback verification fails, stop mutating the host; retain /opt/argus, database volumes, backups/, and update state for investigation.