Create a reusable Quick Proto skill named quick-proto-cli using the SKILL.md content below.

Install it in the right skill folder for the coding agent you are running in. For Codex, use ~/.codex/skills/quick-proto-cli/SKILL.md for a personal skill or .agents/skills/quick-proto-cli/SKILL.md for this repo. For Claude Code, use ~/.claude/skills/quick-proto-cli/SKILL.md for a personal skill or .claude/skills/quick-proto-cli/SKILL.md for this repo.

If you cannot write to the right folder, create the file in the current repo and tell me the exact path.

SKILL.md:

---
name: quick-proto-cli-api-key
description: Use the Quick Proto CLI with the API-key implementation to publish static prototype builds, HTML artifacts, and starter zips to https://quick-proto.co.uk for shareable preview URLs.
---

# Quick Proto CLI With API Keys

Use this skill when a coding agent needs to publish, download, or manage Quick Proto preview artifacts from a shell using `npx quick-proto-cli` and a Quick Proto API key.

Quick Proto production is `https://quick-proto.co.uk`. The published CLI targets production by default, so normal agent workflows do not need a `--base-url` flag.

## What The CLI Does

The CLI talks to the Quick Proto app over HTTPS with a Bearer API key. It can:

- list the organizations available to the API-key owner
- upload an immutable static preview version from a zip
- upload a single HTML document as a preview version
- download a preview version zip
- upload or download starter/scaffold zips
- upload a preview bundle and starter together with `release`
- set project visibility for shareable preview access

Preview URLs use this host pattern:

```text
https://<version>--<project>--<org>.quick-proto.co.uk
https://latest--<project>--<org>.quick-proto.co.uk
```

`latest` is a rolling alias. Do not use `latest` as an uploaded version slug.

## API Key Setup

Create an API key in the Quick Proto app while signed in:

```text
https://quick-proto.co.uk/settings/api-keys
```

The key represents the signed-in user. That user must belong to the target organization and have permission to upload or update the project.

Never commit API keys, paste them into source files, or print them in final user-facing output.

## Authentication Options

Preferred local agent setup is the CLI's saved login:

```bash
npx quick-proto-cli auth login
npx quick-proto-cli orgs list --json
```

If the user is not authenticated, tell them to create an API key in Quick Proto Settings, then run:

```bash
npx quick-proto-cli auth login
```

The command prompts for the API key and saves it locally. For non-interactive setup, agents may save credentials with stdin:

```bash
printf '%s\n' '{"apiKey":"<quick-proto-api-key>"}' | npx quick-proto-cli auth login --stdin
```

This writes `~/.config/quick-proto/credentials.json` with file mode `0600`. The file stores:

```json
{
  "baseUrl": "https://quick-proto.co.uk",
  "apiKey": "<quick-proto-api-key>"
}
```

Credential resolution order:

1. `--base-url` and `--api-key` flags
2. `PROTO_BASE_URL`, then `BETTER_AUTH_URL`, for the platform origin
3. `QP_API_KEY` for the API key
4. stored credentials in `~/.config/quick-proto/credentials.json`
5. built-in production origin `https://quick-proto.co.uk`

If a user pasted an Authorization header value, the CLI strips a leading `Bearer ` automatically.

Use `QP_API_KEY` or `--api-key` for CI/scripts and one-off commands only:

```bash
export QP_API_KEY="<quick-proto-api-key>"
npx quick-proto-cli orgs list --json
```

To remove saved credentials:

```bash
npx quick-proto-cli auth logout
```

## Default Agent Flow: Publish A Static Build

Use this flow when the user asks for a shareable preview link.

1. Confirm authentication:

```bash
npx quick-proto-cli orgs list --json
```

Expected success includes `ok: true`, `userId`, and `orgs[]` containing `id`, `slug`, `name`, and `role`.

If authentication fails with a missing API key error, exit code `2`, HTTP `401`, or HTTP `403`, tell the user to authenticate with:

```bash
npx quick-proto-cli auth login
```

They should paste a valid Quick Proto API key from `https://quick-proto.co.uk/settings/api-keys` when prompted. After login, rerun `npx quick-proto-cli orgs list --json`.

2. Choose the organization slug.

If `orgs[]` has one item, use that item's `slug`. If there are multiple organizations and the user has not specified one, ask which org to publish under.

3. Choose the project slug.

Derive it from the package name or current folder name:

- lowercase
- replace scopes like `@scope/name` with `name` or `scope-name`
- use only lowercase letters, digits, and single hyphens
- keep it 1-40 characters

The first successful version upload creates the project if it does not already exist.

4. Choose the version slug.

Good options:

- `v1`, `v2`, `v3` when incrementing known project versions
- the short git SHA from `git rev-parse --short HEAD`
- an ISO date such as `2026-06-08`

Rules:

- 1-40 characters
- lowercase letters, digits, and single hyphens
- no leading or trailing hyphen
- no contiguous `--`
- must not be the literal `latest`

5. Build the app.

Use the project's existing build command, usually:

```bash
npm run build
```

Static output directories are commonly `dist`, `build`, or `out`.

For Next.js, upload only a static export tree such as `out`. Do not upload `.next`, because `.next` is a server build rather than a static preview bundle.

6. Validate the output.

The preview zip must contain `index.html` at the zip root or inside one top-level folder. The zip must be non-empty and at most 100 MB.

7. Zip the static output from inside the output folder so `index.html` lands at the archive root:

```bash
(cd dist && zip -r ../quick-proto-bundle.zip .)
```

Adjust `dist` to the real output directory.

8. Upload the preview bundle:

```bash
npx quick-proto-cli version upload \
  -o "$ORG" \
  -p "$PROJECT" \
  -v "$VERSION" \
  -f quick-proto-bundle.zip \
  --latest true \
  --summary "Published by coding agent from the current static build." \
  --json
```

9. Make the project shareable, unless the user requested restricted access:

```bash
npx quick-proto-cli project visibility \
  -o "$ORG" \
  -p "$PROJECT" \
  public \
  --json
```

10. Return both links:

```text
Pinned:  https://<version>--<project>--<org>.quick-proto.co.uk
Latest:  https://latest--<project>--<org>.quick-proto.co.uk
```

## Upload One HTML File

Use `upload-html` for a single generated HTML artifact or a simple static page:

```bash
npx quick-proto-cli version upload-html \
  -o "$ORG" \
  -p "$PROJECT" \
  -v "$VERSION" \
  --html-file index.html \
  --latest true \
  --summary "Single HTML artifact upload." \
  --json
```

HTML can also come from stdin:

```bash
npx quick-proto-cli version upload-html \
  -o "$ORG" \
  -p "$PROJECT" \
  -v "$VERSION" \
  --stdin \
  --latest true \
  --json < index.html
```

Provide exactly one of `--html`, `--html-file`, or `--stdin`.

## Upload A Starter Or Scaffold

Starter zips can contain any layout and are used as downloadable source/scaffold material for a project.

Upload a starter after the project exists:

```bash
npx quick-proto-cli starter upload \
  -o "$ORG" \
  -p "$PROJECT" \
  -s source \
  -f starter.zip \
  --json
```

`scaffold upload` is an alias:

```bash
npx quick-proto-cli scaffold upload \
  -o "$ORG" \
  -p "$PROJECT" \
  -s source \
  -f starter.zip \
  --json
```

For new projects, upload the preview version first. A starter upload before the project exists returns `404`.

## Release: Preview Plus Starter

Use `release` when the user wants a preview bundle and starter zip uploaded together. The command uploads the preview bundle first, then the starter, which is the correct ordering for new projects.

```bash
npx quick-proto-cli release \
  -o "$ORG" \
  -p "$PROJECT" \
  -v "$VERSION" \
  --bundle quick-proto-bundle.zip \
  --starter starter.zip \
  --starter-slug source \
  --latest true \
  --summary "Preview bundle and source starter uploaded by coding agent." \
  --json
```

## Download Commands

Download a preview version:

```bash
npx quick-proto-cli version download \
  -o "$ORG" \
  -p "$PROJECT" \
  -v "$VERSION" \
  --out downloaded-preview.zip \
  --json
```

Download a starter:

```bash
npx quick-proto-cli starter download \
  -o "$ORG" \
  -p "$PROJECT" \
  -s source \
  --out downloaded-starter.zip \
  --json
```

Public projects may allow starter download without a Bearer key. Restricted projects require an API key or session accepted by the server.

## Visibility

Set visibility with:

```bash
npx quick-proto-cli project visibility \
  -o "$ORG" \
  -p "$PROJECT" \
  <public|organization|invite_only|private> \
  --json
```

Use `public` for "anyone with the link" previews.

Use `organization`, `invite_only`, or `private` only when the user asks for restricted access.

## Command Reference

```text
npx quick-proto-cli [--json] [--base-url <url>] [--api-key <key>] <command>
```

Common commands:

```text
auth login [--stdin]
auth logout
orgs list [--json]
version upload -o <org> -p <project> -v <version> -f <path.zip> [--latest true|false] [--summary <text>] [--summary-file <path>] [--json]
version upload-html -o <org> -p <project> -v <version> (--html <text>|--html-file <path>|--stdin) [--latest true|false] [--summary <text>] [--summary-file <path>] [--json]
version download -o <org> -p <project> -v <version> --out <path.zip> [--json]
starter upload -o <org> -p <project> -s <slug> -f <path.zip> [--json]
starter download -o <org> -p <project> -s <slug> --out <path.zip> [--json]
scaffold upload -o <org> -p <project> -s <slug> -f <path.zip> [--json]
scaffold download -o <org> -p <project> -s <slug> --out <path.zip> [--json]
release -o <org> -p <project> -v <version> --bundle <preview.zip> --starter <starter.zip> [--starter-slug source] [--latest true|false] [--summary <text>] [--summary-file <path>] [--json]
project visibility -o <org> -p <project> <public|organization|invite_only|private> [--json]
```

Always use `--json` when another program or agent needs to parse the output.

## API Routes Used By The CLI

The CLI API-key implementation uses these production routes:

```text
GET    /api/cli/me
POST   /api/bundles/:org/:project/:version/upload
POST   /api/bundles/:org/:project/:version/upload/:uploadId/complete
POST   /api/bundles/:org/:project/:version
POST   /api/bundles/:org/:project/:version/html
GET    /api/bundles/:org/:project/:version
POST   /api/bundles/:org/:project/starters/:slug/upload
POST   /api/bundles/:org/:project/starters/:slug/upload/:uploadId/complete
POST   /api/bundles/:org/:project/starters/:slug
GET    /api/bundles/:org/:project/starters/:slug
PATCH  /api/bundles/:org/:project
```

Uploads prefer presigned direct-to-storage PUT sessions when available. If presigned upload setup is unavailable and the server allows fallback, the CLI falls back to direct multipart upload.

## Exit Codes

```text
0 success
1 usage, validation, or most 4xx API errors
2 auth errors: HTTP 401 or 403
3 network or transport errors
4 server errors: HTTP 5xx
```

With `--json`, errors are emitted to stderr as JSON:

```json
{
  "ok": false,
  "error": "Invalid API key.",
  "httpStatus": 401
}
```

Success payloads are emitted to stdout and include `ok: true`.

## Failure Handling

Use these signals to recover quickly:

| Signal | Likely Cause | Agent Action |
| --- | --- | --- |
| missing API key error | no saved credentials, `QP_API_KEY`, or `--api-key` | tell user to run `npx quick-proto-cli auth login` |
| HTTP 401 | missing, invalid, or wrong-site API key | tell user to run `npx quick-proto-cli auth login` with a key from `https://quick-proto.co.uk/settings/api-keys` |
| HTTP 403 | key owner lacks permission or org membership | ask for an org/project where the key owner has access |
| HTTP 404 on starter upload | project does not exist yet | upload a preview version first, or use `release` |
| HTTP 409 on version upload | version slug already exists | choose a new immutable version slug |
| HTTP 422 on version upload | zip is malformed or lacks `index.html` | rebuild and zip from inside the static output directory |
| HTTP 413 | zip exceeds 100 MB | reduce assets or upload a smaller bundle |
| exit code 3 | network or DNS problem | retry once, then report the transport failure |
| exit code 4 | server failure | retry later or report the server status |

## Agent Safety Rules

- Do not reveal the API key in responses, logs, commits, or generated files.
- Do not add `~/.config/quick-proto/credentials.json` to a repository.
- Do not upload server-only build outputs such as `.next`.
- Do not use `latest` as a concrete version slug.
- Do not ask for an org slug if `orgs list --json` returns exactly one org.
- Do ask for an org slug when multiple memberships exist and the user has not specified the target org.
- Prefer `public` visibility only for explicit shareable-link requests.
- Include the pinned and latest HTTPS URLs in the final response after a successful publish.