git.stella-ops.org/docs/modules/cli/guides/setup-guide.md

# Setup Wizard Guide

This guide covers the current `stella setup` command set for installation-scoped control-plane bootstrap.

## Overview

`stella setup` is no longer an all-in-one platform onboarding wizard.

- It owns only the five control-plane steps the running platform can truthfully validate and converge: `database`, `cache`, `migrations`, `admin`, `crypto`.
- It uses the Platform setup session APIs as the source of truth. Local files are not the authoritative setup state.
- Tenant onboarding such as integrations, secrets providers, advisory sources, environments, agents, and notifications happens on the authenticated `/setup/*` surfaces and the corresponding CLI command groups.

## Quick Start

```bash
# Run the installation bootstrap
stella setup run

# Resume the current installation session
stella setup resume

# Show the current installation-scoped session
stella setup status

# JSON status for automation
stella setup status --json

# Probe a specific step only
stella setup run --step database --dry-run

# Reset a specific step
stella setup reset --step cache

# Reset the whole installation session
stella setup reset --all --force
```

## Supported Steps

| Step | Purpose | Notes |
| --- | --- | --- |
| `database` | Verify the PostgreSQL runtime connection and record convergence | Machine-level DB provisioning remains outside `stella setup`. |
| `cache` | Verify the cache runtime connection and record convergence | `valkey` remains a compatibility alias. |
| `migrations` | Converge required schema migrations | Uses the backend migration-admin path. |
| `admin` | Ensure the bootstrap administrator exists | `authority` and `users` remain compatibility aliases. |
| `crypto` | Validate and apply the selected crypto profile | Uses live provider health rather than optimistic local state. |

Deprecated setup aliases still accepted:
- `valkey -> cache`
- `authority -> admin`
- `users -> admin`

Former setup targets such as `vault`, `registry`, `scm`, `sources`, `notify`, `telemetry`, `llm`, `settingsstore`, `environments`, and `agents` now return explicit handoff guidance instead of pretending they are bootstrap steps.

## Command Surface

### `stella setup`

Runs the same flow as `stella setup run`.

Global options:
- `--config`, `-c` - path to YAML configuration used to seed draft values before probe/apply
- `--non-interactive`, `-y` - do not prompt for missing values

### `stella setup run`

Run the installation bootstrap from the beginning or continue from the active installation-scoped session.

Options:
- `--step`, `-s` - run one supported control-plane step only
- `--skip` - skip selected steps for this invocation
- `--dry-run` - probe only; do not apply
- `--force`, `-f` - start a fresh setup session even if one already exists
- `--config`, `-c`
- `--non-interactive`, `-y`

Notes:
- `probe` is diagnostic only. A successful probe does not complete a step.
- Only `apply` transitions performed by `run` without `--dry-run` can converge a step.

### `stella setup resume`

Resume the current setup session or a specific one.

Options:
- `--session` - explicit setup session ID

### `stella setup status`

Show the current installation-scoped session.

Options:
- `--session` - explicit setup session ID
- `--json` - machine-readable output

### `stella setup reset`

Reset one step or the whole installation session.

Options:
- `--step`, `-s` - reset one control-plane step
- `--all` - start a fresh installation-scoped session
- `--force`, `-f` - skip confirmation when used with `--all`

### `stella setup validate`

Validate a configuration file, then run the setup flow in probe-only mode.

Options:
- `--config`, `-c` - required YAML configuration path

## Configuration File Shape

`stella setup` consumes only the values relevant to the five control-plane steps. The CLI forwards these as backend draft values rather than directly mutating local infrastructure.

```yaml
database:
  connectionString: Host=postgres.stella-ops.local;Port=5432;Database=stellaops;Username=stellaops;Password=${DB_PASSWORD}
  host: postgres.stella-ops.local
  port: 5432
  database: stellaops
  user: stellaops
  password: ${DB_PASSWORD}

cache:
  host: cache.stella-ops.local
  port: 6379
  password: ${CACHE_PASSWORD}
  database: 0

users:
  superuser:
    username: admin
    email: admin@example.com
    password: ${ADMIN_PASSWORD}
    displayName: Stella Admin

authority:
  provider: standard

crypto:
  provider: default
```

## What Happens After Setup

When `stella setup` finishes, the next work is tenant onboarding, not more bootstrap steps.

Typical next commands:

```bash
# Discover writable secret-authority targets
stella config integrations secrets targets

# Stage a GitLab access token into a secret-authority target
stella config integrations secrets upsert-bundle \
  --bundle gitlab-server \
  --target <vault-integration-id> \
  --path gitlab/server \
  --entry access-token=glpat-...

# Create the GitLab server integration with the returned authref
stella config integrations create \
  --name local-gitlab \
  --type scm \
  --provider gitlabserver \
  --endpoint http://gitlab.stella-ops.local:8929 \
  --authref authref://vault/gitlab/server#access-token
```

UI handoff surfaces:
- `/setup/integrations/secrets`
- `/setup/integrations/scm`
- `/setup/integrations/ci`
- `/setup/integrations/registries`

## Troubleshooting

### Database probe fails

```bash
stella setup run --step database --dry-run --config ./setup.yaml
```

Check:
- the runtime PostgreSQL service is reachable
- the connection string or host/user/password values are correct
- the machine/bootstrap layer already provisioned PostgreSQL

### Cache probe fails

```bash
stella setup run --step cache --dry-run --config ./setup.yaml
```

Check:
- the runtime cache service is reachable
- the host/port/password values are correct

### Setup reports that `vault` or `scm` is no longer a supported step

That is expected. Those flows moved out of installation bootstrap.

Use:
- `stella config integrations secrets *`
- `stella config integrations create`
- the authenticated `/setup/integrations/*` UI

## Related Commands

- `stella setup status --json`
- `stella config integrations providers`
- `stella config integrations secrets targets`
- `stella config integrations secrets upsert-bundle`
- `stella system migrations-status --module all`