Headless & Scripted Bootstrap

The Setup Wizard is the browser path to a working server. For automation — CI, infrastructure-as-code, a server with no display — Cremind exposes the same actions through the cremind setup CLI. This page covers the headless first-run flow and the recovery commands around it.

The cremind setup group has two halves with different auth requirements:

• Unauthenticated bootstrap — status, complete, reset-orphaned. These deliberately ignore CREMIND_TOKEN, because they are how you obtain a token in the first place.
• Admin-authenticated maintenance — reconfigure, server-config get/set. These require a valid admin CREMIND_TOKEN.

The first-run flow

The typical headless bootstrap is three steps: confirm the server is fresh, POST the setup payload to mint a token, then export that token for the rest of the CLI.

# 1. Confirm the server has not been set up yet
cremind setup status

setup_complete  false

# 2. POST the wizard payload and capture the minted admin JWT
export CREMIND_TOKEN=$(cremind setup complete --json-file bootstrap.json --json | jq -r .token)

# 3. Verify the identity is now usable
cremind me

Checking status

cremind setup status [--profile <name>]

The optional --profile flag additionally reports whether a specific profile already exists. The output is a small key/value table:

Completing setup and minting the token

cremind setup complete POSTs the setup payload — the same data the wizard would collect — and returns a freshly minted admin JWT. This is the only unauthenticated way to mint a token; every other path requires an existing one.

cremind setup complete [--profile <name>] (--json '<inline>' | --json-file <path|->)

• --json — the payload as an inline JSON object.
• --json-file — a path to a JSON file, or - to read stdin.
• --profile — overrides the profile field inside the payload.

If you supply neither --json nor --json-file, the payload is read from stdin. --json and --json-file are mutually exclusive.

On success the command prints profile, expires_at, and token to stdout, and writes a ready-to-copy export CREMIND_TOKEN=... line to stderr. Because a process cannot mutate your shell, either copy that line or capture the token in a subshell (as in step 2 above).

The setup payload

The body matches the wizard one-for-one. The first profile must be named admin, and a profile field is required either inside the JSON or via --profile.

{
  "profile": "admin",
  "server_config": {
    "jwt_secret": "...",
    "user_working_dir": "..."
  },
  "llm_config": {
    "anthropic.api_key": "sk-...",
    "auth_method": "anthropic"
  },
  "tool_configs": {
    "<tool_id>": { "_enabled": "true", "VAR_NAME": "value" }
  },
  "agent_configs": {
    "<tool_id>": {
      "llm_provider": "anthropic",
      "llm_model": "claude-..."
    }
  }
}

A minimal payload only needs the profile and an LLM provider:

{
  "profile": "admin",
  "server_config": { "user_working_dir": "/srv/cremind" },
  "llm_config":    { "anthropic.api_key": "sk-...", "auth_method": "anthropic" }
}

Recovery and re-running

Re-run the wizard from a healthy server

An admin can reset setup_complete so the wizard runs again on the next boot — for example after rotating the JWT secret. This requires admin auth.

cremind setup reconfigure        # invalidates setup_complete
unset CREMIND_TOKEN              # the old token is no longer needed
cremind setup complete --json-file bootstrap.json

Recover an orphaned setup

If setup_complete is true but no profiles exist — for example after the profile table was wiped — the server is "orphaned". This unauthenticated command clears the flag so setup complete can run again:

cremind setup reset-orphaned
cremind setup status

setup_complete  false

The server itself verifies the orphaned state; the call is rejected if the database is in any other condition.

Troubleshooting

• a 'profile' field is required — setup complete saw neither a profile key in the JSON nor a --profile flag. Add one or the other.
• --json and --json-file are mutually exclusive — pick one payload source. To read stdin, omit both or pass --json-file -.
• 401 Unauthorized on reconfigure / server-config — these need admin auth. Confirm CREMIND_TOKEN belongs to an admin profile with cremind me.
• reset-orphaned rejected — the recovery path only fires when the database is genuinely orphaned. Run cremind setup status first to confirm.

Next steps