@secondlayer/cli 10.3.1 → 10.4.0

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 +60 -58
  2. package/dist/cli.js +225 -155
  3. package/dist/cli.js.map +42 -41
  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,64 +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> --subgraph <name> --table <name> [--runtime <inngest\|trigger\|cloudflare\|node>] [--url <url>]` | Subgraph subscription (optional local receiver scaffold) |
85
- | `sl subscriptions create <name> --url <url> --trigger '<json>'` | Chain subscription (repeat `--trigger` or pass `--triggers-file`) |
86
- | `sl subscriptions list` / `get <id\|name>` | List or show config + delivery state |
87
- | `sl subscriptions update <id\|name> --url <url> [--filter key.gte=value]` | Patch URL, filter, format, retry, etc. |
88
- | `sl subscriptions pause/resume <id\|name>` | Stop or restart delivery |
89
- | `sl subscriptions rotate-secret <id\|name>` | Rotate signing secret (printed once) |
90
- | `sl subscriptions deliveries/dead <id\|name>` | Recent attempts / dead-letter rows |
91
- | `sl subscriptions requeue <id\|name> <outboxId>` | Requeue one dead-letter row |
92
- | `sl subscriptions replay <id\|name> --from-block <n> --to-block <n>` | Enqueue a historical block range |
93
- | `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 |
94
96
 
95
97
  Read/action commands support `--json`. Destructive commands prompt unless
96
98
  `-y` / `--yes`. Filters are schema-aware: unknown tables/columns, bad operators,
97
99
  and non-scalar columns are rejected before the API call.
98
100
 
99
101
  Subscriptions are **subgraph** (a table's rows) or **chain** (raw events, no
100
- subgraph). `sl subscriptions create` with `--subgraph`/`--table` makes the
102
+ subgraph). `secondlayer subscriptions create` with `--subgraph`/`--table` makes the
101
103
  first. Pass `--trigger` or `--triggers-file` for the second. SDK, REST, and
102
- MCP take the same `triggers` array. Every other `sl subscriptions` command
104
+ MCP take the same `triggers` array. Every other `secondlayer subscriptions` command
103
105
  operates on both kinds.
104
106
 
105
107
  ### Other
106
108
 
107
109
  | Command | What it does |
108
110
  |---|---|
109
- | `sl contracts generate [files...]` (alias `gen`) | Generate TS interfaces from Clarity contracts |
110
- | `sl context` | Instance snapshot — Streams + Index tips, subgraphs, subscriptions |
111
- | `sl doctor` / `sl status` | Reachability + health checks |
112
- | `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 |
113
115
 
114
116
  ## Environment variables
115
117
 
116
118
  | Var | Purpose |
117
119
  |---|---|
118
- | `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 |
119
121
  | `SL_API_URL` | Instance API. Default `http://127.0.0.1:3800` |
120
122
  | `SL_PLATFORM_API_URL` | Alias of `SL_API_URL` |
121
123
  | `STACKS_NETWORK` | Default network (also via `--network <local\|testnet\|mainnet>`) |
122
- | `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 |
123
125
 
124
- ## Code generation (`sl contracts generate`)
126
+ ## Code generation (`secondlayer contracts generate`)
125
127
 
126
128
  Generate type-safe interfaces, functions, and optional React hooks from Clarity
127
129
  contracts — local `.clar` files, deployed contracts (network inferred from
128
130
  address prefix), or globs.
129
131
 
130
132
  ```bash
131
- sl contracts generate ./contracts/token.clar -o ./src/generated.ts
132
- sl contracts generate SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
133
- sl contracts generate "./contracts/*.clar" -o ./src/generated.ts
134
- 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
135
137
  ```
136
138
 
137
139
  Config-driven:
138
140
 
139
141
  ```bash
140
142
  # write a secondlayer.config.ts, then:
141
- sl contracts generate # regenerates from the config
143
+ secondlayer contracts generate # regenerates from the config
142
144
  ```
143
145
 
144
146
  ```typescript
@@ -179,14 +181,14 @@ const supply = await token.vars.totalSupply.get()
179
181
 
180
182
  ## Frozen commands
181
183
 
182
- Local-dev periphery: still functional, hidden from `sl --help`, no further
184
+ Local-dev periphery: still functional, hidden from `secondlayer --help`, no further
183
185
  investment — may be removed in a future major. The hosted dev loop
184
- (`sl subgraphs create/deploy`) is the supported path.
186
+ (`secondlayer subgraphs create/deploy`) is the supported path.
185
187
 
186
- - `sl local up/down/start/stop/restart/status/logs` — local stack + dev services
187
- - `sl local node ...` — local Stacks node management
188
- - `sl local db ...` — local source DB inspection
189
- - `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
190
192
 
191
193
  ## Docs
192
194