# Subplan 03 - CLI And CI Integration

## Goal

Make `dist` useful from CI before the admin UI exists.

## Commands

`dist server`:

- starts `distd`
- accepts config file and env overrides

`dist doctor`:

- checks config, database, storage directory, HTTPS base URL, and platform tools

`dist app create`:

- creates an app
- accepts slug, display name, owner, platform ids

`dist token create`:

- creates scoped CI tokens
- prints raw token once

`dist ci publish`:

- validates manifest
- creates/fetches app
- creates draft release
- uploads artifacts
- validates artifacts
- publishes release
- optionally promotes a channel
- prints JSON output

`dist release promote`:

- promotes a release to a channel
- checks policy gates

`dist release rollback`:

- moves a channel pointer to the previous valid release

## Manifest Shape

Required fields:

- app slug
- version
- channel
- artifacts list

Artifact fields:

- platform
- path
- filename override
- content type override
- metadata

## Slice 1 - Parser And Help

Deliver:

- Top-level parser.
- Subcommand parser.
- Help text.
- Exit code contract.

Acceptance:

- Unknown commands produce readable errors.
- `--json` never emits human-only text on stdout.

## Slice 2 - Local Publish

Deliver:

- `dist ci publish --manifest dist.json --local-store .dist`
- In-memory or file-backed local mode for early testing.

Acceptance:

- CI flow can be dogfooded without a running HTTP server.

## Slice 3 - Remote Publish

Deliver:

- HTTP client integration.
- Token auth.
- Streaming uploads with SHA-256.
- Retry policy for safe requests.

Acceptance:

- Upload output includes release id, artifact ids, digests, and URLs.

## Slice 4 - CI Templates

Deliver:

- GitHub Actions example.
- GitLab CI example.
- Generic shell example.

Acceptance:

- Users can copy the command and only set server, token, and manifest path.

## Slice 5 - Observability

Deliver:

- Structured logs.
- `--verbose`.
- Machine-readable errors under `--json`.

Acceptance:

- CI logs explain what failed without leaking tokens.