@secondlayer/cli 12.1.0 → 13.0.0

package/README.md

@@ -26,15 +26,29 @@ export SL_API_KEY=<INSTANCE_TOKEN>
 
 ```bash
 bun add -g @secondlayer/cli
-secondlayer init --network mainnet
-secondlayer start --print
-# docker compose -f docker/oss/docker-compose.yml up -d
+secondlayer setup
 
 secondlayer subgraphs scaffold SP1234ABCD.my-contract -o subgraphs/my-contract.ts
 secondlayer subgraphs deploy subgraphs/my-contract.ts --start-block <recent-block>
 secondlayer subgraphs query my-contract <table> --sort _block_height --order desc
 ```
 
+`secondlayer setup` is a guided wizard: it picks network + node mode (with the
+RAM/disk floor shown live), generates secrets, writes `docker-compose.yml` and
+`.env` into a target directory, brings the stack up, prints the observer
+stanza for an external node, and restores + verifies history from the
+archive — the one-command replacement for `init` → hand-copy secrets →
+`docker compose up` → `observer` → `bootstrap` → `verify`. Without a TTY (or
+with `--yes`), it skips the interactive prompts and runs from flags instead;
+`--network` and `--node-mode` are then required, and `--against` is required
+unless you pass `--skip-bootstrap`:
+
+```bash
+secondlayer setup --yes \
+  --network mainnet --node-mode external \
+  --against https://archive.secondlayer.tools/latest.json
+```
+
 `secondlayer subgraphs scaffold` writes the definition file, creates/updates
 `package.json`, and runs `bun install` (pass `--no-install` to skip).
 
@@ -46,12 +60,50 @@ No account. Writes `.env.local`, restores history, prints the Stacks observer st
 
 | Command | What it does |
 |---|---|
+| `secondlayer setup [--network …] [--node-mode external\|stacks\|full] [--api-port <spec>] [--dir <path>] [--against <manifest>] [--skip-bootstrap] [--skip-verify] [--yes] [--force]` | Guided self-host onboarding — secrets, compose + `.env`, docker up, observer stanza, bootstrap, verify. TUI when interactive; flags-only (no prompts) with `--yes` or no TTY |
 | `secondlayer init [--network mainnet\|testnet\|devnet] [--api-url <url>] [--force]` | Write `.env.local` (token, secrets key, webhook signing key). Idempotent |
 | `secondlayer start [--print]` | Validate one-box config and print `docker compose up` |
 | `secondlayer bootstrap --against <manifest> [--to-block <n>] [--public-key <pem>] [-y] [--json]` | Restore chain history from a verified archive into an empty database. Exit `0` restored, `1` diverged, `2` refused |
 | `secondlayer observer [--mode indexer\|signer-shared] [--endpoint host:port] [--recovery journal\|archive] [--network …]` | Print the `[[events_observer]]` stanza. Signer-shared requires `--recovery` |
 | `secondlayer verify [all\|raw\|decode:<name>\|subgraph:<name>] --against <manifest> [--quick\|--deep\|--anchor]` | Compare local data to a signed archive. Default target `raw`. Exit `0` clean, `1` diverged, `2` unanchored |
-| `secondlayer repair --against <archive> [--apply]` | Plan (default) or apply an archive repair |
+| `secondlayer repair --against <archive> [--apply] [-y]` | Plan (default) or apply an archive repair |
+
+Bootstrap and repair against the official hosted archive (`archive.secondlayer.tools`)
+are metered per partition; against any other manifest (a mirror, a teammate's
+box, a local file) they are free. See [Metered fetches](#metered-fetches).
+
+### Metered fetches
+
+`secondlayer bootstrap` and `secondlayer repair` pull partitions from the
+signed archive instead of replaying the chain, and that pull costs money only
+when it targets the official hosted archive. Point `--against` at a mirror or
+a local manifest and nothing is charged, nothing is even contacted beyond
+that manifest, because self-hosting the archive is a supported way to use
+these commands, not a workaround.
+
+Against the official host, both commands quote before they charge:
+
+1. The manifest's partition list is priced with a free, no-write call
+   (`POST /api/archive/quote`).
+2. The quote prints into the existing plan output, for example
+   `metered: 528 partitions ≈ $44.00 · balance $50.00`, or for `repair`
+   inside its monthly allowance, `metered: free (4 of 6 monthly repair
+   fetches remaining)`.
+3. You confirm, or pass `-y` to skip the prompt. `-y` never skips the quote
+   or the balance check: if the balance is short, the command exits before
+   any partition is fetched and prints the shortfall and
+   `secondlayer credits buy`.
+4. Only then does the command fetch, and only the partitions it actually
+   reads are charged.
+
+A partition already charged in the last 24 hours re-presigns for free, so a
+resumed or retried bootstrap never pays twice for the same bytes. `repair`
+gets 6 free range-bundles a month; `bootstrap` does not, since it is the
+whole-chain operation the free tier exists to not subsidize.
+
+`secondlayer verify` is unaffected: it reads manifests and digests, never
+partition bytes, and stays free and anonymous no matter which archive it
+points at.
 
 ### Subgraphs
 
@@ -59,22 +111,22 @@ No account. Writes `.env.local`, restores history, prints the Stacks observer st
 |---|---|
 | `secondlayer subgraphs create <name>` | Scaffold a definition file |
 | `secondlayer subgraphs scaffold <SP...::contract> [-o <path>] [--no-install]` | Generate a subgraph from a deployed contract |
-| `secondlayer subgraphs deploy <file> [--start-block <n>] [--visibility public\|private]` | Deploy; `--start-block` overrides the definition. Deploys default `public` |
+| `secondlayer subgraphs deploy <file> [--start-block <n>]` | Deploy; `--start-block` overrides the definition |
 | `secondlayer subgraphs list` | List deployments (`ls` alias) |
 | `secondlayer subgraphs dev <file>` | Watch + hot-redeploy |
 | `secondlayer subgraphs query <name> <table>` | Query a table with filters, sort, pagination |
 | `secondlayer subgraphs status <name>` / `gaps <name>` | Inspect a deployment |
 | `secondlayer subgraphs spec <nameOrFile> [--format openapi\|agent\|markdown]` | Export API docs for a deployed subgraph or a local definition file |
-| `secondlayer subgraphs codegen <file> --target prisma\|drizzle [-o <path>]` | Generate a typed ORM schema for the subgraph's tables |
-| `secondlayer subgraphs client <name> -o <path>` | Generate a typed query client for a deployed subgraph |
-| `secondlayer subgraphs reindex/backfill/cancel/delete <name>` | Manage processing |
+| `secondlayer codegen subgraph <file> --target kysely\|prisma\|drizzle [-o <path>]` | Generate a typed ORM schema for the subgraph's tables |
+| `secondlayer codegen client <name> -o <path>` | Generate a typed query client for a deployed subgraph |
+| `secondlayer subgraphs reindex/backfill/stop/delete <name>` | Manage processing |
 
 ### Data products (reads)
 
 | Command | What it does |
 |---|---|
 | `secondlayer index ft-transfers` / `nft-transfers` / `events --event-type <t>` / `contract-calls` | Decoded Index layer. Anonymous reads OK |
-| `secondlayer streams tip` / `events` / `consume` / `reorgs` / `canonical <h>` / `pull` | Raw chain event firehose. **Requires `SL_API_KEY`** |
+| `secondlayer streams tip` / `events` / `consume` / `reorgs` / `canonical <h>` / `dumps` | Raw chain event firehose. **Requires `SL_API_KEY`** |
 
 Reads emit JSON to stdout (`--json` accepted across all read commands); `-o/--output` is a file path, not a format.
 
@@ -107,7 +159,7 @@ operates on both kinds.
 
 | Command | What it does |
 |---|---|
-| `secondlayer contracts generate [files...]` (alias `gen`) | Generate TS interfaces from Clarity contracts |
+| `secondlayer codegen contracts [files...]` | Generate TS interfaces from Clarity contracts |
 | `secondlayer context` | Instance snapshot — Streams + Index tips, subgraphs, subscriptions |
 | `secondlayer doctor` / `secondlayer status` | Reachability + health checks |
 | `secondlayer config get/set/reset/delete` | Inspect or reset local config |
@@ -120,26 +172,26 @@ operates on both kinds.
 | `SL_API_URL` | Instance API. Default `http://127.0.0.1:3800` |
 | `SL_PLATFORM_API_URL` | Alias of `SL_API_URL` |
 | `STACKS_NETWORK` | Default network (also via `--network <local\|testnet\|mainnet>`) |
-| `HIRO_API_KEY` | Used by `secondlayer contracts generate` for remote contract fetches |
+| `HIRO_API_KEY` | Used by `secondlayer codegen contracts` for remote contract fetches |
 
-## Code generation (`secondlayer contracts generate`)
+## Code generation (`secondlayer codegen contracts`)
 
 Generate type-safe interfaces, functions, and optional React hooks from Clarity
 contracts — local `.clar` files, deployed contracts (network inferred from
 address prefix), or globs.
 
 ```bash
-secondlayer contracts generate ./contracts/token.clar -o ./src/generated.ts
-secondlayer contracts generate SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
-secondlayer contracts generate "./contracts/*.clar" -o ./src/generated.ts
-secondlayer contracts generate --watch   # regenerate on .clar / config / Clarinet.toml changes
+secondlayer codegen contracts ./contracts/token.clar -o ./src/generated.ts
+secondlayer codegen contracts SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
+secondlayer codegen contracts "./contracts/*.clar" -o ./src/generated.ts
+secondlayer codegen contracts --watch   # regenerate on .clar / config / Clarinet.toml changes
 ```
 
 Config-driven:
 
 ```bash
 # write a secondlayer.config.ts, then:
-secondlayer contracts generate  # regenerates from the config
+secondlayer codegen contracts  # regenerates from the config
 ```
 
 ```typescript