@starkscan/cli 0.1.0-beta.1 → 0.1.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 (15) hide show
  1. package/README.md +75 -99
  2. package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-cli-manifest.json +5 -5
  3. package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-darwin-aarch64.tar.gz +0 -0
  4. package/artifacts/v0.1.0/starkscan-darwin-aarch64.tar.gz.sha256 +1 -0
  5. package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-darwin-x86_64.tar.gz +0 -0
  6. package/artifacts/v0.1.0/starkscan-darwin-x86_64.tar.gz.sha256 +1 -0
  7. package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-linux-aarch64.tar.gz +0 -0
  8. package/artifacts/v0.1.0/starkscan-linux-aarch64.tar.gz.sha256 +1 -0
  9. package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-linux-x86_64.tar.gz +0 -0
  10. package/artifacts/v0.1.0/starkscan-linux-x86_64.tar.gz.sha256 +1 -0
  11. package/package.json +1 -1
  12. package/artifacts/v0.1.0-beta.1/starkscan-darwin-aarch64.tar.gz.sha256 +0 -1
  13. package/artifacts/v0.1.0-beta.1/starkscan-darwin-x86_64.tar.gz.sha256 +0 -1
  14. package/artifacts/v0.1.0-beta.1/starkscan-linux-aarch64.tar.gz.sha256 +0 -1
  15. package/artifacts/v0.1.0-beta.1/starkscan-linux-x86_64.tar.gz.sha256 +0 -1
package/README.md CHANGED
@@ -1,137 +1,113 @@
1
1
  # @starkscan/cli
2
2
 
3
- Command-line launcher for Starkscan API, export, and agent workflows.
3
+ Command-line Starkscan client for status checks, explorer reads, local exports,
4
+ and agent setup.
4
5
 
5
- Status: public beta. Use a smoked exact version such as `0.1.0-beta.1` for unattended
6
- agents or production services.
6
+ Status: public `0.1.0` stable release. The npm `latest` tag points to the real
7
+ CLI package. Use the untagged install for normal setup and pin `0.1.0` for
8
+ unattended agents or production services that need reproducible installs.
7
9
 
8
10
  ## Install
9
11
 
10
12
  ```bash
11
- npm install -g @starkscan/cli@0.1.0-beta.1
12
- starkscan init
13
+ npm install -g @starkscan/cli
14
+ starkscan doctor
13
15
  ```
14
16
 
15
- One-off agent run:
17
+ One-off agent setup without a global install:
16
18
 
17
19
  ```bash
18
- npx -y @starkscan/cli@0.1.0-beta.1 init --agent --output-format json
20
+ npx -y @starkscan/cli init --agent --output-format json
19
21
  ```
20
22
 
21
- For unattended agents or production services, pin a smoked exact version instead
22
- of floating on `@beta`.
23
+ Exact pin for unattended services:
23
24
 
24
- ## What it does
25
+ ```bash
26
+ npx -y @starkscan/cli@0.1.0 init --agent --output-format json
27
+ ```
25
28
 
26
- - Runs the prebuilt native `starkscan` binary without requiring a Rust toolchain.
27
- - Verifies bundled native archives against release-manifest checksums.
28
- - Calls the hosted Starkscan API with request IDs and route-class headers.
29
- - Exposes shell-friendly output for agents, scripts, exports, and operator
30
- smoke checks.
29
+ The `@beta` tag remains a prerelease channel only. Do not use it for unattended
30
+ production services unless a maintainer explicitly asks you to test a
31
+ prerelease.
31
32
 
32
- ## Trust status
33
+ ## First commands
33
34
 
34
- - npm: <https://www.npmjs.com/package/@starkscan/cli>
35
- - public trust docs: <https://starkscan.co/docs/build/package-trust>
36
- - machine-readable matrix: <https://starkscan.co/public-client-surface-matrix.json>
37
- - Socket signal: <https://socket.dev/npm/package/@starkscan/cli>
35
+ ```bash
36
+ export STARKSCAN_API_KEY="<store this in your shell or agent secret store>"
37
+ export STARKSCAN_CHAIN="SN_MAIN"
38
+ # Optional: only set this for preview or self-hosted hosts.
39
+ # export STARKSCAN_BASE_URL="https://preview.example.com/api"
38
40
 
39
- Socket is an external package-risk signal, not a formal Starkscan security
40
- certificate. Starkscan package promotion also requires bundled-artifact checksum
41
- verification, manual passkey or Trusted Publishing/OIDC publish control, and
42
- the launch gates documented at the public package trust page. The canonical
43
- source repository is private, so public package trust links intentionally point
44
- to Starkscan docs instead of GitHub.
41
+ starkscan status
42
+ starkscan block 8279910
43
+ starkscan tx 0x1234abcd
44
+ starkscan search 0x1234abcd
45
+ ```
45
46
 
46
- The wrapper uses bundled native artifacts when they are present in the published package, verifies downloaded or bundled archives against checksums in the release manifest, rejects malformed archives, caches the native `starkscan` binary, and forwards all arguments to it. It does not require a Rust toolchain or repository access.
47
+ The CLI defaults to `https://api.starkscan.co`, sends `X-Starkscan-Api-Key`,
48
+ and uses the same REST API contract as the SDK. MCP uses a separate
49
+ transport: `POST https://api.starkscan.co/mcp` on the API domain, or
50
+ `POST {appBaseUrl}/api/mcp` on app-origin deployments.
47
51
 
48
- Agents can inspect the launcher decision without executing the native binary:
52
+ ## Why use it
53
+
54
+ - No Rust toolchain or private repository access required.
55
+ - Prebuilt native `starkscan` binaries are bundled in the npm package.
56
+ - Bundled or downloaded native archives are verified against manifest checksums
57
+ before execution.
58
+ - `--output-format json` keeps stdout parseable for agents and CI.
59
+ - Stable exit classes make automation predictable: success, usage, auth,
60
+ rate-limit, timeout, and not-found errors are distinct.
61
+ - MCP helpers print ready-to-paste Codex, Claude Code, Cursor, Claude Desktop,
62
+ and Cline configs with environment placeholders, not secret values.
63
+
64
+ ## Agent setup
49
65
 
50
66
  ```bash
51
- npx -y @starkscan/cli@0.1.0-beta.1 --launcher-json
67
+ npx -y @starkscan/cli@0.1.0 init --agent --output-format json
68
+ npx -y @starkscan/cli@0.1.0 mcp print-config --transport remote
69
+ npx -y @starkscan/cli@0.1.0 mcp start --transport remote
52
70
  ```
53
71
 
54
- `--launcher-json` also works through `STARKSCAN_LAUNCHER_JSON=1` or
55
- `STARKSCAN_CLI_LAUNCHER_JSON=1`. The JSON includes the package version,
56
- resolved binary path, release tag, source (`bundled`, `download`, `bin-path`, or
57
- `unknown` for legacy caches without valid sidecar metadata), cache-hit status, and
58
- verification status. It may resolve and verify the binary first, but it does
59
- not invoke the native `starkscan` executable.
72
+ `print-config` emits machine-readable snippets. Keep `STARKSCAN_API_KEY` in the
73
+ host shell, CI secret store, or MCP client secret store.
74
+
75
+ ## Launcher inspection
60
76
 
61
- MCP client setup uses the same package. `print-config` emits machine-readable
62
- Codex and Claude Code snippets with environment-variable placeholders, not
63
- secret values. `start` is the stable alias for serving the remote stdio bridge:
77
+ Agents can inspect the launcher decision without executing the native binary:
64
78
 
65
79
  ```bash
66
- npx -y @starkscan/cli@0.1.0-beta.1 init --agent --output-format json
67
- npx -y @starkscan/cli@0.1.0-beta.1 mcp print-config --transport remote
68
- npx -y @starkscan/cli@0.1.0-beta.1 mcp start --transport remote
80
+ npx -y @starkscan/cli@0.1.0 --launcher-json
69
81
  ```
70
82
 
71
- ## Environment
83
+ The JSON includes the package version, resolved binary path, release tag,
84
+ source (`bundled`, `download`, `bin-path`, or `unknown` for legacy caches),
85
+ cache-hit status, and verification status.
72
86
 
73
- ```bash
74
- export STARKSCAN_API_KEY="mzk_test_your_key_here"
75
- export STARKSCAN_CHAIN="SN_MAIN"
76
- # Optional: only set this for preview or self-hosted hosts.
77
- # export STARKSCAN_BASE_URL="https://preview.example.com/api"
78
- ```
87
+ ## Trust and safety
88
+
89
+ - npm package: <https://www.npmjs.com/package/@starkscan/cli>
90
+ - CLI docs: <https://starkscan.co/docs/ai/agent-cli>
91
+ - API key setup: <https://starkscan.co/api-key>
92
+ - Package trust: <https://starkscan.co/docs/build/package-trust>
93
+ - Machine-readable launch matrix: <https://starkscan.co/public-client-surface-matrix.json>
94
+ - Socket signal: <https://socket.dev/npm/package/@starkscan/cli>
79
95
 
80
- `STARKSCAN_*` is the public CLI environment contract. The launcher still accepts
81
- the old internal variable names as hidden compatibility aliases during the beta
82
- cutover. The CLI defaults to `https://api.starkscan.co` and sends
83
- `X-Starkscan-Api-Key` to the hosted API.
96
+ Socket is an external package-risk signal, not a Starkscan security certificate.
97
+ The public trust source is Starkscan docs because the canonical engineering
98
+ repository is private. Package promotion also requires checked release scripts,
99
+ native artifact checksum verification, npm Trusted Publishing/OIDC for CI
100
+ publishes, and live smoke proof against the hosted API.
84
101
 
85
- The native CLI forwards public API keys only to Starkscan HTTPS hosts or
102
+ The CLI forwards public API keys only to Starkscan HTTPS hosts or
86
103
  localhost/loopback fixtures. When intentionally testing a private API host, pass
87
104
  `--allow-untrusted-base-url` explicitly so keys are not replayed to an
88
105
  unexpected endpoint by default.
89
106
 
90
- Supported `STARKSCAN_CHAIN` values are `SN_MAIN` and `SN_SEPOLIA`. Global flags
91
- can be placed before or after the subcommand, for example
92
- `starkscan status --output-format json --pretty`.
93
-
94
- For agent callers, `--output-format json` always keeps stdout parseable: success
95
- prints `{ "ok": true, "data": ... }`, and failures before a result payload is
96
- emitted print
97
- `{ "ok": false, "error": { "code": "auth_error", "message": "HTTP 401: unauthorized", "exitCode": 3, "exitClass": "auth", "httpStatus": 401, "requestId": "starkscan-cli-..." } }`
98
- before exiting non-zero. Diagnostic commands such as `doctor` can emit
99
- `{ "ok": false, "data": ... }` with a non-zero exit. `stream-json` failures
100
- print one compact `type: "error"` line. Text mode keeps human-readable errors on
101
- stderr.
102
-
103
- Transaction hashes, addresses, token addresses, and calldata values must be
104
- `0x`-prefixed Starknet field elements. Contract-read selectors can be function
105
- names such as `balanceOf` or selector felts. Malformed values fail locally before
106
- any network request with exit code `2`; JSON mode emits `code: "usage_error"`.
107
- In JSON output, address-shaped fields such as `address`, `fromAddress`,
108
- `toAddress`, `contractAddress`, and `tokenAddress` are canonicalized to lowercase
109
- `0x` plus 64 hex characters so agents can join rows reliably. Hashes, calldata,
110
- selectors, and other felt values are not rewritten.
111
-
112
- CLI exit codes are stable for agents: `0` success, `1` runtime, `2`
113
- usage/bad input, `3` auth, `4` rate-limited, `5` timeout, and `6` not found.
114
-
115
- ## Minimal commands
116
-
117
- ```bash
118
- npx -y @starkscan/cli@0.1.0-beta.1 init
119
- npx -y @starkscan/cli@0.1.0-beta.1 status
120
- npx -y @starkscan/cli@0.1.0-beta.1 doctor
121
- npx -y @starkscan/cli@0.1.0-beta.1 mcp print-config --transport remote
122
- ```
123
-
124
107
  ## Release binding
125
108
 
126
- By default, the package resolves to bundled artifacts under `artifacts/v<package-version>` when published with native binaries included. Maintainers can override the release source for tests or emergency rollback:
127
-
128
- - `STARKSCAN_CLI_RELEASE_TAG`: release tag, or `latest`
129
- - `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR`: maintainer/test override for the bundled artifact root. Use an absolute path in CI, or a cwd-relative path locally, pointing to a root that contains `artifacts/v<release-tag>/starkscan-cli-manifest.json` and matching platform archives. Example: `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR=/tmp/starkscan-cli-artifacts npx -y @starkscan/cli@0.1.0-beta.1 doctor`
130
- - `STARKSCAN_CLI_RELEASE_BASE_URL`: maintainer/test release base URL override. Published public packages use bundled artifacts first; beta clients should not set this. By default the override must be a local `file:` URL, the official GitHub HTTPS release path, or Starkscan HTTPS. Custom HTTPS hosts or GitHub repo paths require `STARKSCAN_CLI_ALLOW_CUSTOM_RELEASE_BASE_URL=1`; plaintext HTTP requires `STARKSCAN_CLI_ALLOW_INSECURE_RELEASE_BASE_URL=1` and is limited to localhost or loopback maintainer fixtures. Network release manifests are fail-closed unless `STARKSCAN_CLI_ALLOW_UNSIGNED_NETWORK_MANIFEST=1` is set for a maintainer-only fallback; bundled npm artifacts or local `file:` fixtures are preferred until signed manifest verification exists.
131
- - `STARKSCAN_CLI_CACHE_DIR`: cache root for downloaded native binaries
132
- - `STARKSCAN_CLI_BIN_PATH`: maintainer/test override to use an existing local `starkscan` binary and skip download. Requires `STARKSCAN_CLI_ALLOW_BIN_PATH=1`; the path must be absolute, executable, and not a symlink.
133
- - `STARKSCAN_CLI_RELEASE_REPO`: maintainer/test GitHub repo path override
134
- - `STARKSCAN_CLI_PLATFORM_OVERRIDE`: force a specific target platform for cross-platform testing
135
- - `STARKSCAN_CLI_DOWNLOAD_TIMEOUT_MS`: download inactivity timeout in milliseconds, default `120000`
136
-
137
- The package expects release assets produced by `rust-exp/scripts/package-starkscan-cli.sh`: `starkscan-cli-manifest.json`, `starkscan-<platform>.tar.gz`, and matching checksums. Run native packaging and npm packaging from the repository root so `.artifacts/release/cli` is available. Publish the tarball produced by `scripts/package-starkscan-cli-npm.sh` or `scripts/publish-public-cli.sh`; do not publish the package directory directly, because that can omit native artifacts.
109
+ The package resolves bundled artifacts under `artifacts/v<package-version>` when
110
+ published with native binaries included. Maintainer overrides such as
111
+ `STARKSCAN_CLI_RELEASE_TAG`, `STARKSCAN_CLI_RELEASE_BASE_URL`,
112
+ `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR`, and `STARKSCAN_CLI_BIN_PATH` exist for
113
+ tests and emergency rollback; public clients should not need them.
package/artifacts/{v0.1.0-beta.1 → v0.1.0}/starkscan-cli-manifest.json RENAMED
@@ -1,34 +1,34 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-06-29T04:53:36Z",
3
+ "generatedAt": "2026-06-29T13:07:15Z",
4
4
  "artifacts": [
5
5
  {
6
6
  "name": "starkscan-darwin-aarch64.tar.gz",
7
7
  "platform": "darwin-aarch64",
8
8
  "target": "darwin-aarch64",
9
9
  "archive": "starkscan-darwin-aarch64.tar.gz",
10
- "sha256": "b33a14b7b4e85ee571ee537e46153ea0ef5eb1eb01d6d34c3620c670c13cb371"
10
+ "sha256": "f09d9f6e76be371e0f87da9d1540a77607c37cabb94c69c59959c02cbf523a14"
11
11
  },
12
12
  {
13
13
  "name": "starkscan-darwin-x86_64.tar.gz",
14
14
  "platform": "darwin-x86_64",
15
15
  "target": "darwin-x86_64",
16
16
  "archive": "starkscan-darwin-x86_64.tar.gz",
17
- "sha256": "4bcf906defb317754d38c72a9586219eadfcb9dc725aa920a4fce650c78cf311"
17
+ "sha256": "46319387c9b77503a79dc617fc28aa6b35ba34edda3a6997ce70701591f51885"
18
18
  },
19
19
  {
20
20
  "name": "starkscan-linux-aarch64.tar.gz",
21
21
  "platform": "linux-aarch64",
22
22
  "target": "linux-aarch64",
23
23
  "archive": "starkscan-linux-aarch64.tar.gz",
24
- "sha256": "a60a493fd6c226b329d9e7a4f1b1c1a0d62a68d59740dd484390306db879bac1"
24
+ "sha256": "767bd29fe5562a3ab114f098eecda36d05e816f48e6f8e57df0f66970897887e"
25
25
  },
26
26
  {
27
27
  "name": "starkscan-linux-x86_64.tar.gz",
28
28
  "platform": "linux-x86_64",
29
29
  "target": "linux-x86_64",
30
30
  "archive": "starkscan-linux-x86_64.tar.gz",
31
- "sha256": "604f25e483adf6b035e37ef803f6e5d5a56bed20b3caa1762d0a46923d384e05"
31
+ "sha256": "2f51b30701dce6502cf4cf070adfcb839c74720015524197de679b65d6d927f5"
32
32
  }
33
33
  ]
34
34
  }
package/artifacts/v0.1.0/starkscan-darwin-aarch64.tar.gz.sha256 ADDED
@@ -0,0 +1 @@
1
+ f09d9f6e76be371e0f87da9d1540a77607c37cabb94c69c59959c02cbf523a14 starkscan-darwin-aarch64.tar.gz
package/artifacts/v0.1.0/starkscan-darwin-x86_64.tar.gz.sha256 ADDED
@@ -0,0 +1 @@
1
+ 46319387c9b77503a79dc617fc28aa6b35ba34edda3a6997ce70701591f51885 starkscan-darwin-x86_64.tar.gz
package/artifacts/v0.1.0/starkscan-linux-aarch64.tar.gz.sha256 ADDED
@@ -0,0 +1 @@
1
+ 767bd29fe5562a3ab114f098eecda36d05e816f48e6f8e57df0f66970897887e starkscan-linux-aarch64.tar.gz
package/artifacts/v0.1.0/starkscan-linux-x86_64.tar.gz.sha256 ADDED
@@ -0,0 +1 @@
1
+ 2f51b30701dce6502cf4cf070adfcb839c74720015524197de679b65d6d927f5 starkscan-linux-x86_64.tar.gz
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@starkscan/cli",
3
3
  "private": false,
4
- "version": "0.1.0-beta.1",
4
+ "version": "0.1.0",
5
5
  "description": "Command-line launcher for Starkscan API, export, and agent workflows.",
6
6
  "license": "MIT",
7
7
  "type": "module",
package/artifacts/v0.1.0-beta.1/starkscan-darwin-aarch64.tar.gz.sha256 DELETED
@@ -1 +0,0 @@
1
- b33a14b7b4e85ee571ee537e46153ea0ef5eb1eb01d6d34c3620c670c13cb371 starkscan-darwin-aarch64.tar.gz
package/artifacts/v0.1.0-beta.1/starkscan-darwin-x86_64.tar.gz.sha256 DELETED
@@ -1 +0,0 @@
1
- 4bcf906defb317754d38c72a9586219eadfcb9dc725aa920a4fce650c78cf311 starkscan-darwin-x86_64.tar.gz
package/artifacts/v0.1.0-beta.1/starkscan-linux-aarch64.tar.gz.sha256 DELETED
@@ -1 +0,0 @@
1
- a60a493fd6c226b329d9e7a4f1b1c1a0d62a68d59740dd484390306db879bac1 starkscan-linux-aarch64.tar.gz
package/artifacts/v0.1.0-beta.1/starkscan-linux-x86_64.tar.gz.sha256 DELETED
@@ -1 +0,0 @@
1
- 604f25e483adf6b035e37ef803f6e5d5a56bed20b3caa1762d0a46923d384e05 starkscan-linux-x86_64.tar.gz