@secondlayer/cli 3.1.0 → 3.1.1

package/README.md

@@ -0,0 +1,128 @@
+# @secondlayer/cli
+
+The Secondlayer CLI — one binary for dedicated Stacks indexing, real-time
+subgraphs, and per-tenant hosting lifecycle.
+
+```bash
+bun add -g @secondlayer/cli
+sl --version
+```
+
+## Quickstart
+
+```bash
+sl login                         # magic-link auth, session cached at ~/.secondlayer/session.json
+sl project create my-app         # scaffold a project
+sl project use my-app            # bind cwd to the project (writes ./.secondlayer/project)
+sl instance create --plan launch # provision dedicated Postgres + API + processor
+sl subgraphs deploy ./x.ts       # deploy to your instance
+```
+
+## Command surface
+
+### Auth (top-level)
+
+| Command | What it does |
+|---|---|
+| `sl login` | Magic-link email → 6-digit code → writes session to `~/.secondlayer/session.json` |
+| `sl logout` | Revokes the session and clears the local file |
+| `sl whoami` | Prints account, active project, instance URL, trial days left |
+
+### Project
+
+Projects are the unit that binds a working directory to a dedicated instance.
+Binding is **per-directory** — `.secondlayer/project` in cwd takes precedence
+over the global default at `~/.secondlayer/config.json:defaultProject`. The
+walk-up stops at `.git` (never crosses repos).
+
+| Command | What it does |
+|---|---|
+| `sl project create [name]` | Scaffold a new project on the platform |
+| `sl project list` | List all projects for the account |
+| `sl project use <slug>` | Write `./.secondlayer/project` — binds cwd to that project |
+| `sl project current` | Prints the resolved slug + the file it was read from |
+
+### Instance (dedicated hosting)
+
+One instance per project. The platform API spawns a dedicated `sl-pg-{slug}`,
+`sl-api-{slug}`, and `sl-proc-{slug}` container set on the hosting side.
+
+| Command | What it does |
+|---|---|
+| `sl instance create --plan <launch\|grow\|scale>` | Provision containers. Boxed reveal of `serviceKey` + `anonKey` (shown once). |
+| `sl instance info` | Plan, status, resource usage, trial days left |
+| `sl instance resize --plan <...>` | Recreate containers with new CPU/memory (~30s downtime) |
+| `sl instance suspend` / `resume` | Stop/start containers, volume preserved |
+| `sl instance keys rotate [--service\|--anon\|--both]` | Bump JWT gen, recreate API container, mint replacement key(s) |
+| `sl instance delete` | Typed-slug confirm, hard teardown |
+| `sl instance db` | Print `ssh -L` command + `DATABASE_URL` for tunneled Postgres access |
+| `sl instance db add-key <path>` | Upload an SSH pubkey to the bastion |
+| `sl instance db revoke-key` | Revoke your bastion access |
+
+### Subgraphs (tenant-scoped)
+
+All tenant-scoped commands auto-mint a 5-minute ephemeral service JWT per
+invocation. No long-lived key on disk.
+
+| Command | What it does |
+|---|---|
+| `sl subgraphs new <name>` | Scaffold a subgraph definition file |
+| `sl subgraphs deploy <file>` | Deploy to the active instance |
+| `sl subgraphs dev <file>` | Watch + hot-redeploy |
+| `sl subgraphs list` | List deployed subgraphs |
+| `sl subgraphs status <name>` | Indexing progress, row counts, gaps |
+| `sl subgraphs query <name> <table>` | Query a subgraph table with filters, sort, pagination |
+| `sl subgraphs reindex <name>` | Drop + re-process from the tip backwards |
+| `sl subgraphs backfill <name>` | Fill a specific block range |
+| `sl subgraphs stop <name>` | Pause processing |
+| `sl subgraphs gaps <name>` | List missing block ranges |
+| `sl subgraphs delete <name>` | Drop the subgraph + its schema |
+| `sl subgraphs scaffold <SP...::contract>` | Generate a starter subgraph from a deployed contract |
+| `sl subgraphs generate <name>` | Regenerate TS types for an existing subgraph |
+
+### Local dev + OSS
+
+| Command | What it does |
+|---|---|
+| `sl local start/stop/restart/status/logs` | Manage the local Docker stack |
+| `sl local node setup/start/stop/...` | Manage the local Stacks node |
+| `sl stack start/stop/restart` | Alias for `sl local` |
+| `sl db blocks/txs/events/gaps/reset/resync` | Inspect the local source DB |
+
+### Other
+
+| Command | What it does |
+|---|---|
+| `sl generate [files...]` (aliases: `gen`, `codegen`) | Generate TS interfaces from Clarity contracts |
+| `sl init` | Scaffold `secondlayer.config.ts` |
+| `sl doctor` | Session + project + instance reachability + trial status check |
+| `sl status` | Platform/instance health |
+| `sl account profile` | Update display name / bio / slug |
+| `sl config show/set/reset/clear` | Inspect or reset local config |
+
+## Environment variables
+
+| Var | Purpose |
+|---|---|
+| `SL_API_URL` | Bypass platform resolution — point at an OSS or internal API directly |
+| `SL_SERVICE_KEY` | Service key when using env-var bypass |
+| `SL_PLATFORM_API_URL` | Override the platform API base (default `https://api.secondlayer.tools`) |
+| `STACKS_NETWORK` | Override via `--network <local\|testnet\|mainnet>` |
+| `HIRO_API_KEY` | Used by `sl generate` for remote contract fetches |
+
+## Error codes
+
+Every tenant-scoped failure surfaces a typed code and an action hint:
+
+| Code | CLI hint |
+|---|---|
+| `SESSION_EXPIRED` | `Session expired. Run: sl login` |
+| `TRIAL_EXPIRED` | `Your trial expired. Run: sl instance resize --plan <...> and add payment` |
+| `TENANT_SUSPENDED` | `Instance is suspended. Run: sl instance resume` |
+| `NO_ACTIVE_PROJECT` | `No project selected. Run: sl project use <slug>` |
+| `NO_TENANT_FOR_PROJECT` | `Project has no instance. Run: sl instance create --plan launch` |
+| `KEY_ROTATED` | Handled transparently — `http.ts` re-mints and retries once |
+
+## License
+
+MIT

package/dist/cli.js

@@ -32410,7 +32410,7 @@ var {
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "3.1.0",
+  version: "3.1.1",
   description: "CLI for subgraphs and blockchain indexing on Stacks",
   type: "module",
   bin: {
@@ -32431,7 +32431,8 @@ var package_default = {
   },
   files: [
     "dist",
-    "templates"
+    "templates",
+    "README.md"
   ],
   scripts: {
     build: "bunup",
@@ -35448,5 +35449,5 @@ registerLocalCommand(program);
 registerAccountCommand(program);
 program.parse();
 
-//# debugId=395566BC0854202D64756E2164756E21
+//# debugId=93095DDF734A3A2E64756E2164756E21
 //# sourceMappingURL=cli.js.map