@starkscan/cli

Command-line Starkscan client for status checks, explorer reads, local exports, and agent setup.

Version 0.5.7 fixes the certificate-trust issue confirmed in 0.5.6. Upgrade existing installations and update any exact version pins in CI or agents:

npm install -g @starkscan/[email protected] --ignore-scripts
starkscan --version

The patched verifier rejects the compromised emSign intermediate certificates, even when an older native trust store contains their roots. Approved corporate and sandbox CAs still work through platform trust, SSL_CERT_FILE and SSL_CERT_DIR. The release also updates archive-decoding and async-runtime dependencies. The certificate issue does not establish that credentials were intercepted.

Install

npm install -g @starkscan/cli
starkscan doctor

One-off agent setup without a global install:

npx -y @starkscan/cli init --agent --output-format json

Exact pin for unattended services:

npx -y @starkscan/[email protected] init --agent --output-format json

Prerelease tags such as @beta are maintainer-directed test channels only. Normal users and agents should use the default package or the exact 0.5.7 pin above.

First commands

export STARKSCAN_API_KEY="<store this in your shell or agent secret store>"
export STARKSCAN_CHAIN="SN_MAIN"
# Optional: only set this for preview or self-hosted hosts.
# export STARKSCAN_BASE_URL="https://preview.example.com/api"

starkscan status
starkscan block 8279910
starkscan tx 0x1234abcd
starkscan search 0x1234abcd
starkscan wallet-asset-discovery 0xWALLET --limit 25
starkscan wallet-state 0xWALLET --mode require_complete --limit 25
starkscan token-holder-screening 0xTOKEN --limit 100 --output-format json
starkscan token-holders 0xTOKEN --limit 100 --output-format json
starkscan verify prepare --help
starkscan verify submit --help
starkscan verify status --help
starkscan verify receipt-check --help

token-holder-screening walks the address-keyed policy Top-N and never claims population completeness, even when nextCursor is null. Historical source corrections can invalidate an unexpired generation's proof without changing its immutable rows. Recheck populationComplete, exact, and certification on every JSON page; a previously certified page does not authorize later pages. token-holders requests holder pages; do not present an exact census unless its JSON has the sealed finalized source with freshness=finalized_generation, valid immutable generation/block/hash/digest IDs, an unexpired expiresAt, populationComplete=true with populationReasonCode=complete_canonical_transfer_coverage, exact=true, truncated=false, and completeness.reasonCode=materialized_snapshot; plus certification.status=certified, validatedAgainst=starknet_rpc_balanceOf, certification.reasonCode=materialized_snapshot, and a valid checkedAt no earlier than updatedAt. Pass each opaque nextCursor back with --cursor unchanged. The canonical cold unavailable holder 200 is the full tuple with snapshot.source=materialized_fungible_balances, snapshot.asOfBlock=null, holderCount=0, holderBalanceTotalRaw=null, no rows, nextCursor=null, and Cache-Control: no-store. It also carries certification.status=unavailable, but that status alone does not mean a generation is absent: a sealed generation may carry unavailable certification while still serving immutable rows with exact=false. It is not an empty population; do not cache it or turn it into a zero holder total. Trust a served generation as a complete population only when completeness.exact is true.

The holders command serves only tokens in the explicit address-keyed producer policy registry and never builds a count or generation on the request path. For token-holders, unknown or terminal non-ERC20 targets return 404, while positive indexed fungible evidence without a current policy returns HTTP 422 with code=unqualified_token_policy. token-holder-screening gates policy membership directly, so every unregistered identity returns the same 422 regardless of indexed discovery evidence. This is terminal, non-retryable eligibility state, not an uncaptured generation: the CLI exits with the stable usage class and JSON output includes error.apiCode="unqualified_token_policy". A qualified token without a current certificate still returns its rows as a non-exact 200. A token without a sealed generation returns the canonical unavailable 200 tuple; transient prepared-serving failures retain retryable 503 and Retry-After.

The CLI defaults to https://api.starkscan.co, sends X-Starkscan-Api-Key, and uses the same REST API contract as the SDK.

The native client keeps its bundled public certificate roots and also loads the platform trust source. On Linux and other environments that set OpenSSL-style trust variables, SSL_CERT_FILE may name a PEM bundle and SSL_CERT_DIR may name one or more certificate directories. This supports explicitly trusted corporate and sandbox TLS interception without an insecure certificate bypass. When a TLS handshake fails, the CLI includes the underlying certificate cause in its error output.

starkscan verify is the public asynchronous contract-verification workflow. Run verify prepare --list with the complete package arguments before writing outputs: it prints the exact selected Scarb.toml, Scarb.lock, and .cairo paths while excluding ordinary secrets, dependency trees, and unrelated files. The CLI then deterministically packages those locked compiler inputs, streams the bounded archive to Starkscan's isolated networkless verifier, reports typed job state, and authenticates a portable Ed25519 receipt offline. See the complete contract-verification guide before submitting private or publishable source.

Why use it

• No Rust toolchain or private repository access required.
• Prebuilt native starkscan binaries are bundled in the npm package.
• Bundled or downloaded native archives are verified against manifest checksums before execution.
• --output-format json keeps stdout parseable for agents and CI.
• Stable exit classes make automation predictable: success, usage, auth, rate-limit, timeout, and not-found errors are distinct.

Agent setup

npx -y @starkscan/[email protected] init --agent --output-format json

init prints setup hints without writing secrets. Keep STARKSCAN_API_KEY in the host shell or CI secret store.

Launcher inspection

Agents can inspect the launcher decision without executing the native binary:

npx -y @starkscan/[email protected] --launcher-json

The JSON includes the package version, resolved binary path, release tag, source (bundled, download, bin-path, or unknown for legacy caches), cache-hit status, and verification status.

Trust and safety

• npm package: https://www.npmjs.com/package/@starkscan/cli
• CLI docs: https://starkscan.co/docs/ai/agent-cli
• API key setup: https://starkscan.co/api-key
• Package trust: https://starkscan.co/docs/build/package-trust
• Machine-readable launch matrix: https://starkscan.co/public-client-surface-matrix.json
• Socket signal: https://socket.dev/npm/package/@starkscan/cli

Socket is an external package-risk signal, not a Starkscan security certificate. The public trust source is Starkscan docs because the canonical engineering repository is private. Package promotion also requires checked release scripts, native artifact checksum verification, npm Trusted Publishing/OIDC for CI publishes, and live smoke proof against the hosted API.

The CLI forwards public API keys only to Starkscan HTTPS hosts or localhost/loopback fixtures. When intentionally testing a private API host, pass --allow-untrusted-base-url explicitly so keys are not replayed to an unexpected endpoint by default.

Release binding

The package resolves bundled artifacts under artifacts/v<package-version> when published with native binaries included. Maintainer overrides such as STARKSCAN_CLI_RELEASE_TAG, STARKSCAN_CLI_RELEASE_BASE_URL, STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR, and STARKSCAN_CLI_BIN_PATH exist for tests and emergency rollback; public clients should not need them.

API key usage

starkscan api-key-usage --output-format json reads the configured workspace key's last 24 hours of recorded HTTP usage across chains. Requires read or prove scope; configured server keys and OAuth credentials cannot access account usage.

The proofUsage object reports proofs completed today in UTC, separate terminal outcomes, queued/running jobs, and daily admitted usage with its limit and remaining budget. All admitted jobs consume budget regardless of outcome. Completion counts include jobs submitted before today. Limits are null when relay configuration is unavailable; remaining budget is not a reservation or permission to submit.