CLI

Stand up an instance, fill it with chain history, and deploy your own tables on top, from one terminal.

Install

bun add -g @secondlayer/cli

The binary is secondlayer. sl is a short alias.

Common commands

secondlayer init --network mainnet
secondlayer bootstrap --against <manifest>
secondlayer observer
secondlayer subgraphs create --from-contract <id>
secondlayer subgraphs deploy
secondlayer subgraphs list
secondlayer subscriptions create
secondlayer context
secondlayer verify all --against <manifest>
secondlayer repair --against <archive>
secondlayer credits buy --email you@example.com --pack 25
secondlayer credits balance
secondlayer credits refill --below 5 --pack 25

Verified archive owns secondlayer verify / secondlayer repair. Self-host is the compose loop. secondlayer credits * meters archive bootstrap and backfill; archive credits.

Chain subscriptions

Direct chain subscriptions take --trigger / --triggers-file instead of --subgraph / --table. SDK and REST accept the same triggers array.

Local runtime

Write keys, restore history, print the observer stanza.

secondlayer init --network mainnet
secondlayer bootstrap --against https://archive.secondlayer.tools/.../snapshots/<digest>.json
secondlayer observer --mode indexer

Command	Flag	Default	Notes
`secondlayer init`	`--network`	`STACKS_NETWORK` or `mainnet`	`mainnet`, `testnet`, or `devnet`
	`--api-url`	`http://127.0.0.1:3800`	Local API
	`--force`	off	Overwrite generated values in `.env.local`
`secondlayer status`	`--json`	off	Local instance health from `/public/status`
`secondlayer bootstrap`	`--against`	required	Manifest URL or file
	`--to-block`	archive tip	Stop early
	`--public-key`	resolved	Pin the signing key
	`-y, --yes`	off	Skip confirm
	`--json`	off	Machine output
`secondlayer observer`	`--mode`	`indexer`	`indexer` retries; `signer-shared` does not
	`--endpoint`	`indexer:3700` (`127.0.0.1:3700` on devnet)	`host:port` only, no URL
	`--recovery`	required for signer-shared	`journal` or `archive`
	`--network`	`STACKS_NETWORK` or `mainnet`	Loopback refused except devnet

secondlayer bootstrap refuses a non-empty database. Fix an existing instance with secondlayer repair. Exit 0 restored, 1 diverged, 2 refused.

secondlayer verify [target] compares local data to a signed archive. Target is all, raw (default), decode:<name>, or subgraph:<name>. --quick is identity; --deep is semantic; --anchor requires a verified signature. Flags live on Verified archive.

Signer-shared nodes skip retries

--mode signer-shared requires --recovery journal or --recovery archive. Missed blocks refill from that source.

Scaffold from a contract

secondlayer subgraphs create sbtc-registry \
  --from-contract SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry

Infers each print topic's payload from indexed history; see print schemas. Anonymous. --table-per-topic emits one table per topic.

secondlayer codegen prints <file> emits a .d.ts next to the definition. Incompatible with --target / --models-only / --env. Deploy warnings on unobserved event.data fields are advisory.

Commit your definition before deploying

secondlayer subgraphs deploy checks the source file is committed. An uncommitted deploy leaves the only copy in the database.

A terminal prompts. Scripts and CI fail. --allow-uncommitted overrides and logs the skip. Outside a git repo, and --dry-run, skip the check.

Generate typed contract clients

Turn Clarity contracts into typed TypeScript: local .clar files, deployed contracts, or a Clarinet project.

secondlayer codegen contracts ./contracts/token.clar -o ./src/generated.ts
secondlayer codegen contracts SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
secondlayer codegen contracts --watch    # regenerate on .clar / config / Clarinet.toml changes

Deployed contract ids fetch the ABI (address prefix picks the network). Config-driven projects regenerate with secondlayer codegen contracts:

// secondlayer.config.ts
import { defineConfig } from "@secondlayer/cli";
import { clarinet, react } from "@secondlayer/cli/plugins";

export default defineConfig({
  out: "./src/generated/contracts.ts",
  plugins: [clarinet(), react()],
});

Plugin	What it adds
`clarinet()`	Real ABIs from your Clarinet project via Simnet; typed clients for `[project.requirements]` dependency contracts too (`includeRequirements: false` to opt out)
`react()`	Typed React hooks per contract

Named aliases per function (TokenTransferArgs) plus a TypedAbi const. Feed it to getContract from @secondlayer/stacks; Clarinet tests use the simnet transport.

Frozen features

These work but get no further investment.

secondlayer codegen subgraph --target prisma|drizzle|kysely: typed ORM schema. See Subgraphs.
secondlayer local: superseded by secondlayer devnet. Hidden.