{
  "topic": "cli",
  "path": [
    "cli"
  ],
  "title": "cyoda CLI — subcommand reference",
  "synopsis": "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.",
  "body": "# cli\n\n## NAME\n\ncli — the cyoda command-line interface.\n\n## SYNOPSIS\n\n`cyoda [<subcommand>] [<flags>]`\n\n## DESCRIPTION\n\ncyoda 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.\n\nGlobal flags `--help` (or `-h`) and `--version` (or `-v`) are recognized before subcommand dispatch.\n\n## SUBCOMMANDS\n\n- `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).\n- `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.\n- `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.\n- `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.\n- `cyoda help [<topic>...] [--format=<fmt>]` — Browse the help topic tree. See `cyoda help cli help`. Exit codes: `0` topic found; `1` topic not found.\n\n## OPTIONS\n\n- `--help`, `-h` — Print top-level help summary. Exit code: `0`.\n- `--version`, `-v` — Print the binary's ldflag-injected version, commit SHA, and build date. Exit code: `0`.\n\n## CONFIGURATION\n\nAll 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.\n\n## EXAMPLES\n\n```\n# Start the server with defaults (in-memory storage, mock auth)\ncyoda\n\n# First-run bootstrap then start\ncyoda init && cyoda\n\n# Check version of an installed binary\ncyoda --version\n\n# Run with profiles: postgres storage + observability\nCYODA_PROFILES=postgres,otel cyoda\n\n# Run via docker compose (dev helper)\n./scripts/dev/run-docker-dev.sh\n```\n\n## SEE ALSO\n\n- config\n- run\n- quickstart\n",
  "sections": [
    {
      "name": "NAME",
      "body": "cli — the cyoda command-line interface."
    },
    {
      "name": "SYNOPSIS",
      "body": "`cyoda [<subcommand>] [<flags>]`"
    },
    {
      "name": "DESCRIPTION",
      "body": "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.\n\nGlobal flags `--help` (or `-h`) and `--version` (or `-v`) are recognized before subcommand dispatch."
    },
    {
      "name": "SUBCOMMANDS",
      "body": "- `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).\n- `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.\n- `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.\n- `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.\n- `cyoda help [<topic>...] [--format=<fmt>]` — Browse the help topic tree. See `cyoda help cli help`. Exit codes: `0` topic found; `1` topic not found."
    },
    {
      "name": "OPTIONS",
      "body": "- `--help`, `-h` — Print top-level help summary. Exit code: `0`.\n- `--version`, `-v` — Print the binary's ldflag-injected version, commit SHA, and build date. Exit code: `0`."
    },
    {
      "name": "CONFIGURATION",
      "body": "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."
    },
    {
      "name": "EXAMPLES",
      "body": "```\n# Start the server with defaults (in-memory storage, mock auth)\ncyoda\n\n# First-run bootstrap then start\ncyoda init && cyoda\n\n# Check version of an installed binary\ncyoda --version\n\n# Run with profiles: postgres storage + observability\nCYODA_PROFILES=postgres,otel cyoda\n\n# Run via docker compose (dev helper)\n./scripts/dev/run-docker-dev.sh\n```"
    },
    {
      "name": "SEE ALSO",
      "body": "- config\n- run\n- quickstart"
    }
  ],
  "see_also": [
    "config",
    "run",
    "quickstart"
  ],
  "stability": "stable",
  "actions": [],
  "children": [
    "cli.health",
    "cli.help",
    "cli.init",
    "cli.migrate",
    "cli.serve"
  ]
}