Agent CLI

Use the Starkscan CLI for shell workflows, release validation, and local-first exports.

In this guide

Use this surface for When not to start here Try in app before you script it Install with npm or npx Pinned installer fallback Environment

Loading documentation content…

Agent CLI

Use the CLI when you need reproducible shell commands, local-first exports, or an operator-friendly surface that sits on top of the same Starkscan API contract.

Before using the CLI in unattended workflows, check the Launch matrix for the current release state and manual blockers.

Use this surface for

shell workflows with explicit commands and outputs
local transfer exports and privacy-sensitive analysis
release validation from a terminal
preparing the same binary for stdio MCP in Codex or Claude Code

When not to start here

Use the REST API first when you need zero-install integration.
Use the SDK when you are writing app code.
Use MCP when the consumer is already an MCP client.

Try in app before you script it

The explorer is still the fastest way to understand the data you are about to automate:

Dashboard for top-level chain state
Transactions for rows and detail pages
Contracts for contract metadata and activity
Watchlist for repeat address analysis

Install with npm or npx

npm install -g @mezcal/cli@alpha
mezcal doctor

For a one-off agent run without a global install:

npx @mezcal/cli@alpha doctor

The npm launcher uses native CLI artifacts bundled in the published package when available, verifies archives against the bundled release manifest, rejects malformed archives, caches the native mezcal binary, and forwards all arguments to it. It does not require Rust or repository access.

Starkscan is the public product name. The alpha package and command remain @mezcal/cli and mezcal so existing release artifacts, MCP configs, and installer scripts keep working.

Pinned installer fallback

export MEZCAL_INSTALLER_REF="<release-tag>"
curl -fsSL "https://raw.githubusercontent.com/starknet-innovation/mezcal/${MEZCAL_INSTALLER_REF}/rust-exp/scripts/install-mezcal.sh" | bash -s -- --version "${MEZCAL_INSTALLER_REF}"

The installer downloads the matching GitHub release artifact for your OS/architecture, verifies the .sha256 file, rejects malformed archives, installs mezcal, and confirms mezcal --version before reporting success. Use this path only when you need an explicit release source and have access to the release artifacts.

If you already use Homebrew and are comfortable tracking main:

brew tap starknet-innovation/mezcal https://github.com/starknet-innovation/mezcal
brew install --HEAD starknet-innovation/mezcal/mezcal

If you already use Rust tooling and want a source-based developer fallback:

cargo install --git https://github.com/starknet-innovation/mezcal --branch main rust-exp --bin mezcal

Environment

export MEZCAL_BASE_URL="https://<your-starkscan-host>/api"
export MEZCAL_API_KEY="mzk_live_your_key_here"
export MEZCAL_CHAIN="SN_MAIN"

For hosted external access, keep MEZCAL_BASE_URL on the deployment's /api base. The CLI then calls the normal /v1/* routes underneath that base for you. The CLI sends X-Starkscan-Api-Key for hosted API auth. Keep using the MEZCAL_* env names in this alpha CLI; they are the compatibility contract for the current binary.

If you need a pinned release, pass the tag explicitly:

export MEZCAL_INSTALLER_REF="<release-tag>"
curl -fsSL "https://raw.githubusercontent.com/starknet-innovation/mezcal/${MEZCAL_INSTALLER_REF}/rust-exp/scripts/install-mezcal.sh" | bash -s -- --version "${MEZCAL_INSTALLER_REF}"

Manual tarball install remains available as a maintainer fallback after downloading the matching archive from the GitHub release page:

tar -xzf mezcal-<platform>.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 mezcal "$HOME/.local/bin/mezcal"

Homebrew is currently a developer-oriented --HEAD path. Because the formula lives in this repository, the tap command uses an explicit remote URL. External users should prefer npm unless they have repository or release-artifact access.

Maintainers preparing a GitHub release should package the native CLI and npm launcher through release automation so archives, checksums, the manifest, and the npm tarball are generated together:

./rust-exp/scripts/package-mezcal-cli.sh .artifacts/release/cli
./webapp/packages/cli/scripts/package-mezcal-cli-npm.sh .artifacts/release/npm-cli

Release automation bundles native CLI artifacts into the npm package under the package-version release tag. If a GitHub release is also requested, its tag must match the npm package version tag.

First successful commands

mezcal status

mezcal address-activity 0xwallet --limit 50
mezcal tx-details 0xtxA 0xtxB --log-limit-per-tx 32
mezcal contract-events 0xcontract --topic0 0x... --from-block 7800000 --limit 100
mezcal contract-entrypoints 0xtoken
mezcal contract-read 0xtoken --selector balanceOf --calldata 0xwallet
mezcal token-total-supply 0x0123...
mezcal token-balance-of <ownerAddress> <tokenAddress> --block-tag pending

mezcal token-balance-of intentionally keeps the owner-first CLI order for shell readability. The REST API and SDK remain token-first, so translate it as:

CLI: mezcal token-balance-of <ownerAddress> <tokenAddress>
REST: GET $MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/token/<tokenAddress>/balance-of/<ownerAddress>
SDK: mezcal.tokenBalanceOf(tokenAddress, ownerAddress)

Use that command only when you already know the exact token contract you want. If the workflow is "does this wallet already hold USDC?" or "skip wallets with any nonzero holdings," prefer:

CLI: mezcal address-token-holdings <ownerAddress>
REST: GET $MEZCAL_BASE_URL/v1/$MEZCAL_CHAIN/address/<ownerAddress>/token-holdings

That matters on Starknet because a symbol such as USDC can map to more than one live contract or alias. An exact-token balance-of can return 0 for one USDC contract while the wallet still holds another USDC variant.

If your key class includes holdings access, add:

mezcal address-token-holdings 0xwallet

For large wallet-screening jobs, use address-token-holdings rather than looping token-balance-of for every wallet. Before you make a definitive skip/allow decision from that response, check the holdings completeness flags. Treat the result as complete only when exact=true, truncated=false, and completeness.reasonCode="complete".

General shell workflows

mezcal block 7800000
mezcal tx 0x1234abcd
mezcal tx-details 0x1234abcd 0x5678ef90 --log-limit-per-tx 32
mezcal search 0x1234abcd
mezcal address-activity 0xwallet --limit 50
mezcal address-transactions 0xwallet --limit 50
mezcal contract-events 0xcontract --topic0 0x... --from-block 7800000 --limit 100
mezcal contract-entrypoints 0xtoken
mezcal contract-read 0xtoken --selector balanceOf --calldata 0xwallet
mezcal feed --max-events 10

Local-first transfer exports

mezcal --output-format json token-transfers 0x0123... \
  --address 0x0456... \
  --address 0x0789... \
  --from-block 7800000 \
  --to-block 7802500 > transfers.json

That gives you a narrow token + address(es) + block range export directly on your machine instead of in a shared dump.

For multi-wallet monitoring without a block range, repeat --address the same way:

mezcal token-transfers 0x0123... \
  --address 0xwalletA \
  --address 0xwalletB \
  --limit 100

For the full external starter, including the matching REST and SDK flows plus the shared env contract, use Monitor 10 wallets.

Contract event indexers

mezcal --output-format json contract-events 0xcontract \
  --topic0 0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9 \
  --from-block 7800000 \
  --to-block 7800500 \
  --limit 100

Use contract-events when you need the canonical paginated log stream for one contract before applying protocol-specific decoding. Keep filters server-side first: contract address, exact topic0..topic3, block range, then continue with --cursor.

Batch transaction hydration

mezcal --output-format json tx-details \
  0xabc... \
  0xdef... \
  --log-limit-per-tx 32

Use tx-details when you already have an ordered tx hash list and want bounded Starkscan transaction previews in one batch. Check logsTruncated and tokenTransfersTruncated before treating child arrays as exhaustive. Logs are included by default for this convenience command; pass --no-include-logs when you only need compact preview rows.

Smoke-test the CLI path

MEZCAL_BASE_URL="https://<your-mezcal-host>/api" \
MEZCAL_API_KEY="$MEZCAL_API_KEY" \
./rust-exp/scripts/release-cli-smoke.sh

It validates the commands most release users rely on first:

mezcal status
mezcal block <head>
mezcal tx <sample>
mezcal search <sample>

When to choose another surface

Use the SDK for app code.
Use the REST API for raw HTTP contract debugging.
Use MCP when an agent needs tool calls rather than explicit commands.
Stay in the explorer app when the job is visual investigation instead of automation.