# cyoda init — first-run bootstrap

`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 …

<em>cyoda-go version <a href="https://github.com/Cyoda-platform/cyoda-go/releases/tag/v0.6.2">0.6.2</a></em>

# cli.init

## NAME

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

## SYNOPSIS

`cyoda init [--force]`

## 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

- `--force` — Overwrite an existing user config, or write a user config even when a system config is present.

## 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

```
# 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

- config
- cli.migrate

## See also

- [`cyoda help config`](/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`](/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

- [`/help/cli/init.json`](/help/cli/init.json) — full descriptor (matches `GET /help/{topic}` envelope)
- [`/help/cli/init.md`](/help/cli/init.md) — body only