{
  "topic": "cli.init",
  "path": [
    "cli",
    "init"
  ],
  "title": "cyoda init — first-run bootstrap",
  "synopsis": "`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.",
  "body": "# cli.init\n\n## NAME\n\ncli.init — write a starter user config enabling sqlite.\n\n## SYNOPSIS\n\n`cyoda init [--force]`\n\n## DESCRIPTION\n\n`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.\n\nThe user config file is written to the OS-appropriate XDG config path:\n\n- **Linux / macOS:** `$XDG_CONFIG_HOME/cyoda/cyoda.env` (falls back to `~/.config/cyoda/cyoda.env` if `XDG_CONFIG_HOME` is unset).\n- **Windows:** `%AppData%\\cyoda\\cyoda.env` (falls back to `%USERPROFILE%\\AppData\\Roaming\\cyoda\\cyoda.env`).\n\nThe sqlite database itself defaults to the OS data directory:\n\n- **Linux / macOS:** `$XDG_DATA_HOME/cyoda/cyoda.db` (falls back to `~/.local/share/cyoda/cyoda.db`).\n- **Windows:** `%LocalAppData%\\cyoda\\cyoda.db`.\n\nThe database path can be overridden by setting `CYODA_SQLITE_PATH` in the config or shell environment.\n\n**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.\n\n**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.\n\n## OPTIONS\n\n- `--force` — Overwrite an existing user config, or write a user config even when a system config is present.\n\n## EXIT CODES\n\n- `0` — Success, including the no-op case (config already exists).\n- `1` — I/O error (cannot compute user path, cannot create directory, cannot write file).\n- `2` — Flag-parse error.\n\n## EXAMPLES\n\n```\n# First-run bootstrap: write ~/.config/cyoda/cyoda.env\ncyoda init\n\n# Overwrite an existing user config\ncyoda init --force\n\n# Typical first-run sequence\ncyoda init && cyoda\n```\n\n## SEE ALSO\n\n- config\n- cli.migrate\n",
  "sections": [
    {
      "name": "NAME",
      "body": "cli.init — write a starter user config enabling sqlite."
    },
    {
      "name": "SYNOPSIS",
      "body": "`cyoda init [--force]`"
    },
    {
      "name": "DESCRIPTION",
      "body": "`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.\n\nThe user config file is written to the OS-appropriate XDG config path:\n\n- **Linux / macOS:** `$XDG_CONFIG_HOME/cyoda/cyoda.env` (falls back to `~/.config/cyoda/cyoda.env` if `XDG_CONFIG_HOME` is unset).\n- **Windows:** `%AppData%\\cyoda\\cyoda.env` (falls back to `%USERPROFILE%\\AppData\\Roaming\\cyoda\\cyoda.env`).\n\nThe sqlite database itself defaults to the OS data directory:\n\n- **Linux / macOS:** `$XDG_DATA_HOME/cyoda/cyoda.db` (falls back to `~/.local/share/cyoda/cyoda.db`).\n- **Windows:** `%LocalAppData%\\cyoda\\cyoda.db`.\n\nThe database path can be overridden by setting `CYODA_SQLITE_PATH` in the config or shell environment.\n\n**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.\n\n**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."
    },
    {
      "name": "OPTIONS",
      "body": "- `--force` — Overwrite an existing user config, or write a user config even when a system config is present."
    },
    {
      "name": "EXIT CODES",
      "body": "- `0` — Success, including the no-op case (config already exists).\n- `1` — I/O error (cannot compute user path, cannot create directory, cannot write file).\n- `2` — Flag-parse error."
    },
    {
      "name": "EXAMPLES",
      "body": "```\n# First-run bootstrap: write ~/.config/cyoda/cyoda.env\ncyoda init\n\n# Overwrite an existing user config\ncyoda init --force\n\n# Typical first-run sequence\ncyoda init && cyoda\n```"
    },
    {
      "name": "SEE ALSO",
      "body": "- config\n- cli.migrate"
    }
  ],
  "see_also": [
    "config",
    "cli.migrate"
  ],
  "stability": "stable",
  "actions": []
}