# @quickback-dev/cli

The Quickback CLI — a thin client for the Quickback compiler. Define your backend in TypeScript, run `quickback compile`, and ship a fully wired Cloudflare Worker project with auth, database, migrations, security pillars, CMS, and Account UI already generated.

```bash
# Fastest path — interactive, scaffolds in the current directory
npx @quickback-dev/cli start

# Or, scriptable:
npm i -g @quickback-dev/cli
quickback create cloudflare my-app
cd my-app
quickback compile
```

If a remote compile fails, rerun with `quickback compile --verbose` to show the
failing command, exit code, stderr/stdout tail, and suggested fixes.

Full docs: [docs.quickback.dev](https://docs.quickback.dev)

---

## Commands

| Command | What it does |
|---|---|
| `quickback start` | Interactive one-shot onboarding — picks template, scaffolds, defers login until the compile step. Designed for `npx` in an empty folder. |
| `quickback create <template> <name>` | Scriptable scaffold from a Quickback template (e.g. `cloudflare`, `blog`, `todos`, `saas`) |
| `quickback compile` | Compile your `quickback/quickback.config.ts` + feature definitions into a generated project. Checks managed schema declarations first; pass `--fix-schema` to apply safe additive fixes. |
| `quickback schema check` | Check every authored feature table for canonical managed audit/soft-delete declarations without writing files. |
| `quickback schema sync` | Add missing canonical managed declarations transactionally; divergent authored declarations fail closed for manual review. |
| `quickback example [name]` | Extract a pre-compiled example project (e.g. `recruitment`) into the current directory |
| `quickback login` | Authenticate against `api.quickback.dev` (device flow, opens browser) |
| `quickback logout` | Clear stored credentials |
| `quickback whoami` | Show the currently authenticated account |
| `quickback mcp` | Start a stdio MCP server exposing Quickback docs to AI tools (Claude Desktop, Cursor, etc.) |
| `quickback claude` / `cursor` | Install Quickback's bundled skill / rules into Claude Code or Cursor |

## Project layout

```
my-app/
├── quickback/
│   ├── quickback.config.ts       # providers (cloudflare-d1, better-auth, …), CMS, account, etc.
│   ├── definitions/
│   │   ├── features/<table>/     # schema.ts (Drizzle), resource config (firewall/access/guards/masking)
│   │   └── services/             # queues, realtime, embeddings
│   └── drizzle/                  # migration SQL + meta (compiler-owned, commit this)
├── src/                          # generated runtime — overwritten on every compile
├── wrangler.toml                 # generated
└── package.json
```

## Configuration

| Env var | Purpose | Default |
|---|---|---|
| `QUICKBACK_API_URL` | Compiler endpoint | `https://compiler.quickback.dev` |
| `QUICKBACK_API_KEY` | Skip device-flow login (CI) | — |

## Requirements

- Node.js ≥ 18
- `wrangler` (peer requirement only when deploying the generated Cloudflare Worker)

---

## Security & Supply Chain

If you're using a supply-chain scanner (Socket, Snyk, Sonatype, etc.) you may see findings on this package. We're a small team that takes security seriously — here's what each finding actually is, and why it's there.

### "Network access" (8 transitive packages)

The CLI itself makes exactly **two** outbound requests, both to our own subdomains and both gated behind environment-variable overrides:

- `https://compiler.quickback.dev` — the compile API (`POST /compile`, `GET /templates`, `GET /health`). Source: [`src/lib/api-client.ts`](./src/lib/api-client.ts).
- `https://api.quickback.dev` — auth/device-flow login. Source: [`src/commands/login.ts`](./src/commands/login.ts).

The other 6 transitive packages flagged here (`eventsource`, `eventsource-parser`, `jose`, `pkce-challenge`, `body-parser`, `proxy-addr`) come from the optional MCP SDK transports — see *MCP SDK*, below.

### "Shell access" (2 packages)

`cross-spawn` and `which`/`isexe`, both transitive of `@modelcontextprotocol/sdk`. The CLI's own shell-out is in [`src/lib/shell.ts`](./src/lib/shell.ts) — used to run post-compile commands the compiler returns (e.g. `drizzle-kit generate`, `npm install`). Commands are not user-input-derived; they come from the trusted compile API response and run in your project directory.

### "Install scripts" (1 package)

`esbuild`. esbuild ships a platform-specific native binary that's downloaded by its install script. We use esbuild to parse your `quickback.config.ts` and feature definitions — it's a hard requirement of the CLI. esbuild is one of the most-downloaded packages on npm and is published by the Vercel team.

### "Uses eval" (5 transitive packages)

`ajv`, `kleur`, `qs`, `pkce-challenge`, and one more — none authored by us, none invoked from CLI code. `ajv` (JSON schema) compiles validators via `new Function()`, which scanners flag as eval-equivalent. All are transitive of `@modelcontextprotocol/sdk`.

### "AI-detected possible typosquat: parseuri"

False positive. The flagged package is [`parseurl`](https://www.npmjs.com/package/parseurl) — a 12-year-old Express middleware (~50M weekly downloads), pulled in via the MCP SDK's HTTP transport. Not a typosquat of `parseuri`; the names just rhyme.

### Why MCP SDK is a hard dependency

`@modelcontextprotocol/sdk` powers the `quickback mcp` command — a stdio MCP server that lets Claude Desktop / Cursor / Windsurf read Quickback's documentation as context. We made it a hard dep (rather than a peer dep) so that `quickback mcp` Just Works after a single `npm i -g`, no second install step. The SDK is loaded via dynamic `import()`, so its code never executes unless you actually run `quickback mcp`.

The trade-off: even users who never run `mcp` get its transitive packages in their install tree. We think the UX win is worth it; if you're scanning aggressively and would rather we move it to optional peers, [open an issue](https://github.com/paulstenhouse/quickback-compiler/issues).

### URL strings in the bundle

Most of the URLs Socket finds are inside `src/docs/content.ts` (a JSON dump of the marketing docs we ship for the `quickback help` and `quickback mcp` commands) and `src/skill/SKILL.md` (the Claude Code skill). They're documentation references — never fetched by the CLI.

---

## License

MIT © Kardoe Incorporated

## Links

- [Quickback compiler docs](https://docs.quickback.dev)
- [GitHub repository](https://github.com/paulstenhouse/quickback-compiler)
- [Issue tracker](https://github.com/paulstenhouse/quickback-compiler/issues)
- [Changelog](https://docs.quickback.dev/compiler/changelog)