Skip to content
Cyoda Documentation
Settings

cyoda init — first-run bootstrap

cyoda-go version 0.6.2

cli.init

Section titled “cli.init”

NAME

Section titled “NAME”

cli.init — write a starter user config enabling sqlite.

SYNOPSIS

Section titled “SYNOPSIS”

cyoda init [--force]

DESCRIPTION

Section titled “DESCRIPTION”

cyoda init is the recommended first step for local desktop use. It writes a minimal user config file that sets CYODA_STORAGE_BACKEND=sqlite, enabling persistent local storage without requiring a database server.

The user config file is written to the OS-appropriate XDG config path:

  • Linux / macOS: $XDG_CONFIG_HOME/cyoda/cyoda.env (falls back to ~/.config/cyoda/cyoda.env if XDG_CONFIG_HOME is unset).
  • Windows: %AppData%\cyoda\cyoda.env (falls back to %USERPROFILE%\AppData\Roaming\cyoda\cyoda.env).

The sqlite database itself defaults to the OS data directory:

  • Linux / macOS: $XDG_DATA_HOME/cyoda/cyoda.db (falls back to ~/.local/share/cyoda/cyoda.db).
  • Windows: %LocalAppData%\cyoda\cyoda.db.

The database path can be overridden by setting CYODA_SQLITE_PATH in the config or shell environment.

Idempotency: cyoda init is safe to run more than once. Without --force, it exits 0 immediately if a config already exists (either system-wide or at the user path). It does not modify, migrate, or overwrite existing configs.

System config detection: On Linux, if /etc/cyoda/cyoda.env exists, cyoda init prints a note and exits 0 without writing a user config — a system-wide config already covers the system. Pass --force to write a user config anyway.

OPTIONS

Section titled “OPTIONS”
  • --force — Overwrite an existing user config, or write a user config even when a system config is present.

EXIT CODES

Section titled “EXIT CODES”
  • 0 — Success, including the no-op case (config already exists).
  • 1 — I/O error (cannot compute user path, cannot create directory, cannot write file).
  • 2 — Flag-parse error.

EXAMPLES

Section titled “EXAMPLES”
# First-run bootstrap: write ~/.config/cyoda/cyoda.env
cyoda init


# Overwrite an existing user config
cyoda init --force


# Typical first-run sequence
cyoda init && cyoda

SEE ALSO

Section titled “SEE ALSO”
  • config
  • cli.migrate

See also

Section titled “See also”
  • cyoda help config — Environment variables beat default values. The _FILE suffix variant takes precedence over the plain variable when both are set — for example, CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url wins over CYODA_POSTGRES_URL. There are no command-line flags for configuration values; env vars are the sole configuration surface.
  • cyoda help cli migrate — cyoda migrate is a short-lived process that applies pending schema migrations for the configured storage backend, then exits cleanly — no admin listener, no background loops, no lingering goroutines.

Raw formats

Section titled “Raw formats”