@secondlayer/cli 10.3.0 → 10.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +63 -62
  2. package/dist/cli.js +167 -192
  3. package/dist/cli.js.map +39 -40
  4. package/package.json +2 -2
  5. package/templates/subscriptions/cloudflare/README.md +2 -2
  6. package/templates/subscriptions/node/README.md +2 -2
  7. package/templates/subscriptions/node/src/index.ts +2 -2
  8. package/templates/subscriptions/trigger/README.md +2 -2
package/README.md CHANGED
@@ -5,14 +5,16 @@ subscriptions, and Clarity code generation.
5
5
 
6
6
  ```bash
7
7
  bun add -g @secondlayer/cli
8
- sl --version
8
+ secondlayer --version
9
9
  ```
10
10
 
11
+ `sl` is a short alias of `secondlayer`.
12
+
11
13
  ## Auth
12
14
 
13
15
  Default API is `http://127.0.0.1:3800`. Override with `SL_API_URL`.
14
16
 
15
- Writes against a published bind use `INSTANCE_TOKEN` from `sl init` as
17
+ Writes against a published bind use `INSTANCE_TOKEN` from `secondlayer init` as
16
18
  `SL_API_KEY`. Loopback reads need no token.
17
19
 
18
20
  ```bash
@@ -24,16 +26,16 @@ export SL_API_KEY=<INSTANCE_TOKEN>
24
26
 
25
27
  ```bash
26
28
  bun add -g @secondlayer/cli
27
- sl init --network mainnet
28
- sl start --print
29
+ secondlayer init --network mainnet
30
+ secondlayer start --print
29
31
  # docker compose -f docker/oss/docker-compose.yml up -d
30
32
 
31
- sl subgraphs scaffold SP1234ABCD.my-contract -o subgraphs/my-contract.ts
32
- sl subgraphs deploy subgraphs/my-contract.ts --start-block <recent-block>
33
- sl subgraphs query my-contract <table> --sort _block_height --order desc
33
+ secondlayer subgraphs scaffold SP1234ABCD.my-contract -o subgraphs/my-contract.ts
34
+ secondlayer subgraphs deploy subgraphs/my-contract.ts --start-block <recent-block>
35
+ secondlayer subgraphs query my-contract <table> --sort _block_height --order desc
34
36
  ```
35
37
 
36
- `sl subgraphs scaffold` writes the definition file, creates/updates
38
+ `secondlayer subgraphs scaffold` writes the definition file, creates/updates
37
39
  `package.json`, and runs `bun install` (pass `--no-install` to skip).
38
40
 
39
41
  ## Commands
@@ -44,36 +46,36 @@ No account. Writes `.env.local`, restores history, prints the Stacks observer st
44
46
 
45
47
  | Command | What it does |
46
48
  |---|---|
47
- | `sl init [--network mainnet\|testnet\|devnet] [--api-url <url>] [--force]` | Write `.env.local` (token, secrets key, webhook signing key). Idempotent |
48
- | `sl start [--print]` | Validate one-box config and print `docker compose up` |
49
- | `sl 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 |
50
- | `sl observer [--mode indexer\|signer-shared] [--endpoint host:port] [--recovery journal\|archive] [--network …]` | Print the `[[events_observer]]` stanza. Signer-shared requires `--recovery` |
51
- | `sl 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 |
52
- | `sl repair --against <archive> [--apply]` | Plan (default) or apply an archive repair |
49
+ | `secondlayer init [--network mainnet\|testnet\|devnet] [--api-url <url>] [--force]` | Write `.env.local` (token, secrets key, webhook signing key). Idempotent |
50
+ | `secondlayer start [--print]` | Validate one-box config and print `docker compose up` |
51
+ | `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 |
52
+ | `secondlayer observer [--mode indexer\|signer-shared] [--endpoint host:port] [--recovery journal\|archive] [--network …]` | Print the `[[events_observer]]` stanza. Signer-shared requires `--recovery` |
53
+ | `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 |
54
+ | `secondlayer repair --against <archive> [--apply]` | Plan (default) or apply an archive repair |
53
55
 
54
56
  ### Subgraphs
55
57
 
56
58
  | Command | What it does |
57
59
  |---|---|
58
- | `sl subgraphs create <name>` | Scaffold a definition file |
59
- | `sl subgraphs scaffold <SP...::contract> [-o <path>] [--no-install]` | Generate a subgraph from a deployed contract |
60
- | `sl subgraphs deploy <file> [--start-block <n>] [--visibility public\|private]` | Deploy; `--start-block` overrides the definition. Managed deploys default `public`, BYO default `private` |
61
- | `sl subgraphs list` | List deployments (`ls` alias) |
62
- | `sl subgraphs dev <file>` | Watch + hot-redeploy |
63
- | `sl subgraphs query <name> <table>` | Query a table with filters, sort, pagination |
64
- | `sl subgraphs status <name>` / `gaps <name>` | Inspect a deployment |
65
- | `sl subgraphs spec <nameOrFile> [--format openapi\|agent\|markdown]` | Export API docs for a deployed subgraph or a local definition file |
66
- | `sl subgraphs deploy <file> --database-url <url>` | BYO: write the subgraph's rows to your own Postgres |
67
- | `sl subgraphs codegen <file> --target prisma\|drizzle [-o <path>]` | Generate an ORM schema for the subgraph's tables (BYO DB) |
68
- | `sl subgraphs client <name> -o <path>` | Generate a typed query client for a deployed subgraph |
69
- | `sl subgraphs reindex/backfill/cancel/delete <name>` | Manage processing |
60
+ | `secondlayer subgraphs create <name>` | Scaffold a definition file |
61
+ | `secondlayer subgraphs scaffold <SP...::contract> [-o <path>] [--no-install]` | Generate a subgraph from a deployed contract |
62
+ | `secondlayer subgraphs deploy <file> [--start-block <n>] [--visibility public\|private]` | Deploy; `--start-block` overrides the definition. Managed deploys default `public`, BYO default `private` |
63
+ | `secondlayer subgraphs list` | List deployments (`ls` alias) |
64
+ | `secondlayer subgraphs dev <file>` | Watch + hot-redeploy |
65
+ | `secondlayer subgraphs query <name> <table>` | Query a table with filters, sort, pagination |
66
+ | `secondlayer subgraphs status <name>` / `gaps <name>` | Inspect a deployment |
67
+ | `secondlayer subgraphs spec <nameOrFile> [--format openapi\|agent\|markdown]` | Export API docs for a deployed subgraph or a local definition file |
68
+ | `secondlayer subgraphs deploy <file> --database-url <url>` | BYO: write the subgraph's rows to your own Postgres |
69
+ | `secondlayer subgraphs codegen <file> --target prisma\|drizzle [-o <path>]` | Generate an ORM schema for the subgraph's tables (BYO DB) |
70
+ | `secondlayer subgraphs client <name> -o <path>` | Generate a typed query client for a deployed subgraph |
71
+ | `secondlayer subgraphs reindex/backfill/cancel/delete <name>` | Manage processing |
70
72
 
71
73
  ### Data products (reads)
72
74
 
73
75
  | Command | What it does |
74
76
  |---|---|
75
- | `sl index ft-transfers` / `nft-transfers` / `events --event-type <t>` / `contract-calls` | Decoded Index layer. Anonymous reads OK; free-tier keys rejected (Build+ for keyed) |
76
- | `sl streams tip` / `events` / `consume` / `reorgs` / `canonical <h>` / `pull` | Raw chain event firehose. **Requires `SL_API_KEY`** |
77
+ | `secondlayer index ft-transfers` / `nft-transfers` / `events --event-type <t>` / `contract-calls` | Decoded Index layer. Anonymous reads OK; free-tier keys rejected (Build+ for keyed) |
78
+ | `secondlayer streams tip` / `events` / `consume` / `reorgs` / `canonical <h>` / `pull` | Raw chain event firehose. **Requires `SL_API_KEY`** |
77
79
 
78
80
  Reads emit JSON to stdout (`--json` accepted across all read commands); `-o/--output` is a file path, not a format.
79
81
 
@@ -81,65 +83,64 @@ Reads emit JSON to stdout (`--json` accepted across all read commands); `-o/--ou
81
83
 
82
84
  | Command | What it does |
83
85
  |---|---|
84
- | `sl subscriptions create <name> --runtime <inngest\|trigger\|cloudflare\|node> [--auth-token <token>] [--filter key=value]` | Scaffold a receiver wired to a new subscription |
85
- | `sl subscriptions list` / `get <id\|name>` | List or show config + delivery state |
86
- | `sl subscriptions update <id\|name> --url <url> [--filter key.gte=value]` | Patch URL, filter, format, retry, etc. |
87
- | `sl subscriptions pause/resume <id\|name>` | Stop or restart delivery |
88
- | `sl subscriptions rotate-secret <id\|name>` | Rotate signing secret (printed once) |
89
- | `sl subscriptions deliveries/dead <id\|name>` | Recent attempts / dead-letter rows |
90
- | `sl subscriptions requeue <id\|name> <outboxId>` | Requeue one dead-letter row |
91
- | `sl subscriptions replay <id\|name> --from-block <n> --to-block <n>` | Enqueue a historical block range |
92
- | `sl subscriptions doctor/test <id\|name>` | Health check / signed fixture |
86
+ | `secondlayer subscriptions create <name> --subgraph <name> --table <name> [--runtime <inngest\|trigger\|cloudflare\|node>] [--url <url>]` | Subgraph subscription (optional local receiver scaffold) |
87
+ | `secondlayer subscriptions create <name> --url <url> --trigger '<json>'` | Chain subscription (repeat `--trigger` or pass `--triggers-file`) |
88
+ | `secondlayer subscriptions list` / `get <id\|name>` | List or show config + delivery state |
89
+ | `secondlayer subscriptions update <id\|name> --url <url> [--filter key.gte=value]` | Patch URL, filter, format, retry, etc. |
90
+ | `secondlayer subscriptions pause/resume <id\|name>` | Stop or restart delivery |
91
+ | `secondlayer subscriptions rotate-secret <id\|name>` | Rotate signing secret (printed once) |
92
+ | `secondlayer subscriptions deliveries/dead <id\|name>` | Recent attempts / dead-letter rows |
93
+ | `secondlayer subscriptions requeue <id\|name> <outboxId>` | Requeue one dead-letter row |
94
+ | `secondlayer subscriptions replay <id\|name> --from-block <n> --to-block <n>` | Enqueue a historical block range |
95
+ | `secondlayer subscriptions doctor/test <id\|name>` | Health check / signed fixture |
93
96
 
94
97
  Read/action commands support `--json`. Destructive commands prompt unless
95
98
  `-y` / `--yes`. Filters are schema-aware: unknown tables/columns, bad operators,
96
99
  and non-scalar columns are rejected before the API call.
97
100
 
98
- Subscriptions are polymorphic — **subgraph** (fires on a subgraph table's rows)
99
- or **chain** (fires on raw chain events with no subgraph). `sl subscriptions
100
- create` makes subgraph subscriptions only (via the `--subgraph`/`--table`
101
- flags). Create chain subscriptions — a webhook on a contract / event / function /
102
- trait — via the SDK, REST, or MCP with a `triggers` array. Every other
103
- `sl subscriptions` command (list/get/update/pause/resume/delete/doctor/test/
104
- deliveries/...) operates on both kinds.
101
+ Subscriptions are **subgraph** (a table's rows) or **chain** (raw events, no
102
+ subgraph). `secondlayer subscriptions create` with `--subgraph`/`--table` makes the
103
+ first. Pass `--trigger` or `--triggers-file` for the second. SDK, REST, and
104
+ MCP take the same `triggers` array. Every other `secondlayer subscriptions` command
105
+ operates on both kinds.
105
106
 
106
107
  ### Other
107
108
 
108
109
  | Command | What it does |
109
110
  |---|---|
110
- | `sl contracts generate [files...]` (alias `gen`) | Generate TS interfaces from Clarity contracts |
111
- | `sl context` | Instance snapshot — Streams + Index tips, subgraphs, subscriptions |
112
- | `sl doctor` / `sl status` | Reachability + health checks |
113
- | `sl config get/set/reset/delete` | Inspect or reset local config |
111
+ | `secondlayer contracts generate [files...]` (alias `gen`) | Generate TS interfaces from Clarity contracts |
112
+ | `secondlayer context` | Instance snapshot — Streams + Index tips, subgraphs, subscriptions |
113
+ | `secondlayer doctor` / `secondlayer status` | Reachability + health checks |
114
+ | `secondlayer config get/set/reset/delete` | Inspect or reset local config |
114
115
 
115
116
  ## Environment variables
116
117
 
117
118
  | Var | Purpose |
118
119
  |---|---|
119
- | `SL_API_KEY` | `INSTANCE_TOKEN` from `sl init` for writes. Loopback reads need no token |
120
+ | `SL_API_KEY` | `INSTANCE_TOKEN` from `secondlayer init` for writes. Loopback reads need no token |
120
121
  | `SL_API_URL` | Instance API. Default `http://127.0.0.1:3800` |
121
122
  | `SL_PLATFORM_API_URL` | Alias of `SL_API_URL` |
122
123
  | `STACKS_NETWORK` | Default network (also via `--network <local\|testnet\|mainnet>`) |
123
- | `HIRO_API_KEY` | Used by `sl contracts generate` for remote contract fetches |
124
+ | `HIRO_API_KEY` | Used by `secondlayer contracts generate` for remote contract fetches |
124
125
 
125
- ## Code generation (`sl contracts generate`)
126
+ ## Code generation (`secondlayer contracts generate`)
126
127
 
127
128
  Generate type-safe interfaces, functions, and optional React hooks from Clarity
128
129
  contracts — local `.clar` files, deployed contracts (network inferred from
129
130
  address prefix), or globs.
130
131
 
131
132
  ```bash
132
- sl contracts generate ./contracts/token.clar -o ./src/generated.ts
133
- sl contracts generate SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
134
- sl contracts generate "./contracts/*.clar" -o ./src/generated.ts
135
- sl contracts generate --watch # regenerate on .clar / config / Clarinet.toml changes
133
+ secondlayer contracts generate ./contracts/token.clar -o ./src/generated.ts
134
+ secondlayer contracts generate SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
135
+ secondlayer contracts generate "./contracts/*.clar" -o ./src/generated.ts
136
+ secondlayer contracts generate --watch # regenerate on .clar / config / Clarinet.toml changes
136
137
  ```
137
138
 
138
139
  Config-driven:
139
140
 
140
141
  ```bash
141
142
  # write a secondlayer.config.ts, then:
142
- sl contracts generate # regenerates from the config
143
+ secondlayer contracts generate # regenerates from the config
143
144
  ```
144
145
 
145
146
  ```typescript
@@ -180,14 +181,14 @@ const supply = await token.vars.totalSupply.get()
180
181
 
181
182
  ## Frozen commands
182
183
 
183
- Local-dev periphery: still functional, hidden from `sl --help`, no further
184
+ Local-dev periphery: still functional, hidden from `secondlayer --help`, no further
184
185
  investment — may be removed in a future major. The hosted dev loop
185
- (`sl subgraphs create/deploy`) is the supported path.
186
+ (`secondlayer subgraphs create/deploy`) is the supported path.
186
187
 
187
- - `sl local up/down/start/stop/restart/status/logs` — local stack + dev services
188
- - `sl local node ...` — local Stacks node management
189
- - `sl local db ...` — local source DB inspection
190
- - `sl devnet connect/down/status/logs` — Clarinet devnet integration
188
+ - `secondlayer local up/down/start/stop/restart/status/logs` — local stack + dev services
189
+ - `secondlayer local node ...` — local Stacks node management
190
+ - `secondlayer local db ...` — local source DB inspection
191
+ - `secondlayer devnet connect/down/status/logs` — Clarinet devnet integration
191
192
 
192
193
  ## Docs
193
194