CLI reference
freshdock has three subcommands: check (read-only),
recreate (one container, manual), and
run (the scheduler daemon). Run freshdock --help or
freshdock <command> --help for the same information at the terminal.
Global options
Available on every subcommand.
| Option | Default | Meaning |
|---|---|---|
--no-color | colour on a TTY | Disable ANSI colour. Use for log files / non-interactive output. Setting NO_COLOR to any non-empty value does the same. |
--config <PATH> | see below | Path to an optional freshdock.toml. |
The config file is optional — freshdock is configured primarily through
environment variables and per-container
labels, and a file is only needed to declare notification targets. When you do use
one, the resolution order is --config <PATH> → $FRESHDOCK_CONFIG →
./freshdock.toml. An explicit path that’s missing is an error; a missing default
file is fine. See the configuration reference.
RUST_LOG controls log verbosity (default info; try freshdock=debug or
trace). Secrets are always redacted.
freshdock check
freshdock check
Read-only. Lists every opted-in container (freshdock.enable=true), resolves the
latest digest once per unique image (deduped to conserve Docker Hub’s anonymous
budget of 100 pulls / 6 h — manifest fetches count as pulls), and prints a status
table. It never pulls,
stops, or recreates anything.
The table has six columns: container, image, mode, current digest,
latest digest, and update?. The update? column is yes (a newer digest
exists), no (up to date), or -/? when no comparison was possible. When a digest
can’t be resolved, the latest digest column shows the reason instead:
latest digest value | Meaning |
|---|---|
a short digest (e.g. sha256:ab12cd…) | The resolved upstream digest; compare with update?. |
pinned (no check) | Image is pinned to a digest — no moving tag to follow. |
auth required (set credentials) | The registry needs credentials that aren’t configured. See registry-auth. |
network unavailable | The registry couldn’t be reached; nothing is assumed. |
error: … | The probe failed for another reason (the message follows). |
Examples:
freshdock check # render the table
freshdock --no-color check # ANSI-free, for logs
RUST_LOG=info freshdock check # include registry rate-limit info
freshdock recreate <NAME>
freshdock recreate <NAME>
Manually update one container by name or ID: inspect → pull → stop → rename → create → start, then health-gate the new container and roll back to the previous one if it fails.
| Argument | Meaning |
|---|---|
<NAME> | Name or ID of the running container to recreate. |
It does not consult freshdock.mode (modes drive the scheduler, not manual
intent), but it refuses a container that is freshdock.enable=false or
freshdock.mode=off — a graceful no-op, so you can’t accidentally recreate a
container you’ve explicitly opted out. Any other mode (including watch) is allowed
because you typed the command yourself.
freshdock run
freshdock run [--interval <SECS>] [--tick <SECS>] [--stop-timeout <SECS>]
The scheduler daemon. Each tick it lists running containers, parses their labels,
and acts on the ones that are due: live/nightly/weekly/monthly are updated
(health-gated, with rollback); watch is report-only. Runs in the foreground until
SIGINT/SIGTERM, then finishes the in-flight container and exits. See
scheduling for the timing model.
| Option | Env var | Default | Meaning |
|---|---|---|---|
--interval <SECS> | FRESHDOCK_INTERVAL | 300 | Poll cadence for live and watch containers. |
--tick <SECS> | FRESHDOCK_TICK | 60 | Scheduler loop granularity. Calendar (cron) modes are evaluated once per tick, so this bounds how late a fire can be. |
--stop-timeout <SECS> | FRESHDOCK_STOP_TIMEOUT | 30 | Max seconds to drain in-flight work after a shutdown signal before force-exit. |
The flag wins over its env var; an invalid env value is a startup error.
Examples:
freshdock run # poll live/watch every 5 min; cron modes on schedule
freshdock run --interval 600 # poll every 10 min instead
freshdock run --config /etc/freshdock.toml
RUST_LOG=info freshdock run # per-container scheduler events