# cyoda CLI — subcommand reference

cyoda is a Go binary that embeds the full platform: API server, schema engine, workflow runner, and storage plugins. Invoked with no subcommand, it starts…

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

# cli

## NAME

cli — the cyoda command-line interface.

## SYNOPSIS

`cyoda [<subcommand>] [<flags>]`

## DESCRIPTION

cyoda is a Go binary that embeds the full platform: API server, schema engine, workflow runner, and storage plugins. Invoked with no subcommand, it starts the server using environment-provided configuration. Subcommands provide operational affordances — `init` for first-run bootstrap, `health` for liveness probes, `migrate` for schema migrations.

Global flags `--help` (or `-h`) and `--version` (or `-v`) are recognized before subcommand dispatch.

## SUBCOMMANDS

- `cyoda` (no subcommand) — start the API server. See `cli serve`. Exit codes: `0` clean shutdown after SIGINT/SIGTERM; `1` startup failure (IAM validation, OTel init, port bind, backend connect).
- `cyoda init [--force]` — Write a starter user config enabling sqlite. See `cyoda help cli init`. Exit codes: `0` success or idempotent no-op; `1` I/O error; `2` bad flags.
- `cyoda health` — Probe `/readyz` on the admin listener. See `cyoda help cli health`. Exit codes: `0` readyz returned 200; `1` connection error or non-200 status.
- `cyoda migrate [--timeout <duration>]` — Run schema migrations for the configured backend and exit. See `cyoda help cli migrate`. Exit codes: `0` success or no-op (memory/sqlite); `1` runtime error (bad config, DB unreachable, migration failure, timeout); `2` flag-parse error.
- `cyoda help [<topic>...] [--format=<fmt>]` — Browse the help topic tree. See `cyoda help cli help`. Exit codes: `0` topic found; `1` topic not found.

## OPTIONS

- `--help`, `-h` — Print top-level help summary. Exit code: `0`.
- `--version`, `-v` — Print the binary's ldflag-injected version, commit SHA, and build date. Exit code: `0`.

## CONFIGURATION

All server configuration is via environment variables with the `CYODA_` prefix. Variables can be placed in `.env` files and loaded automatically using profiles. See `cyoda help config` for the full reference.

## EXAMPLES

```
# Start the server with defaults (in-memory storage, mock auth)
cyoda

# First-run bootstrap then start
cyoda init && cyoda

# Check version of an installed binary
cyoda --version

# Run with profiles: postgres storage + observability
CYODA_PROFILES=postgres,otel cyoda

# Run via docker compose (dev helper)
./scripts/dev/run-docker-dev.sh
```

## SEE ALSO

- config
- run
- quickstart

## Subtopics

- [`cyoda help cli health`](/help/cli/health/) — `cyoda health` sends an HTTP GET to `http://127.0.0.1:<port>/readyz` and exits 0 if the server responds with HTTP 200. Any non-200 response or connection error causes exit 1.
- [`cyoda help cli help`](/help/cli/help/) — `cyoda help` is the built-in documentation browser. Topics are organized in a dot-separated tree (`cli`, `cli.serve`, `config.database`, etc.). Invoking `cyoda help` with no arguments prints a summary of all top-level topics. Invoking it with one or more topic segments navigates the tree.
- [`cyoda help cli init`](/help/cli/init/) — `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.
- [`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.
- [`cyoda help cli serve`](/help/cli/serve/) — Starting with no subcommand loads configuration from environment variables, validates the IAM mode, and binds the REST, gRPC, and admin listeners. The server is single-process, multi-tenant, and stateful — storage is provided by one of the pluggable backends (`memory`, `sqlite`, or `postgres`); see `cyoda help config` for backend selection.

## 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 run`](/help/run/) — cyoda-go is a single-process, multi-tenant REST and gRPC API server. It starts in serving mode when invoked with no subcommand. All configuration is via environment variables with a `CYODA_` prefix. The binary, Docker image, and Helm chart run the same binary; only the environment configuration differs across run modes.
- [`cyoda help quickstart`](/help/quickstart/) — cyoda-go is a single-process, multi-tenant REST and gRPC API server backed by a pluggable embedded database management system. Storage backends are `memory`, `sqlite`, and `postgres`; authentication modes are `mock` and `jwt`. All configuration is via environment variables with a `CYODA_` prefix.

## Raw formats

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