Skip to content
nXCC

CLI Reference

The nXCC Command Line Interface (@nxcc/cli) is the primary tool for developing and managing your nXCC projects, workers, and on-chain identities. This tool is designed for developers building applications on nXCC.

Installation

Section titled “Installation”

Install the CLI globally using your preferred package manager:

npm install -g @nxcc/cli

Verify the installation:

nxcc --version

Commands

Section titled “Commands”

nxcc init

Section titled “nxcc init”

Scaffolds a new nXCC project in the specified directory.

nxcc init [directory]
  • [directory] (optional): The directory to create the project in. Defaults to the current directory.

This command creates a basic project structure with a sample worker, a default policy using the NXCC SDK, manifests, and TypeScript configuration, ready for you to start building.

nxcc bundle

Section titled “nxcc bundle”

Creates a self-contained, deployable worker bundle from a manifest template. A bundle is a DSSE-formatted JSON file containing your compiled worker code and metadata.

nxcc bundle <manifest-template>
  • <manifest-template>: Path to the worker manifest template file (e.g., workers/worker.manifest.json).

Options:

  • --out <path>: The output path for the generated bundle file. Defaults to bundle.json in the same directory as the manifest.
  • --signer <private-key>: An Ethereum-style private key (hex format, 0x...) to sign the bundle’s DSSE envelope.

nxcc worker

Section titled “nxcc worker”

Commands for deploying and interacting with workers.

nxcc worker deploy

Section titled “nxcc worker deploy”

Deploys a worker to an nXCC node by submitting a “work order”.

nxcc worker deploy <manifest-path>
  • <manifest-path>: Path to the worker’s manifest file.

Options:

  • --rpc-url <url>: The HTTP RPC URL of the target nXCC node. Defaults to http://localhost:6922 (first node started by ./node/run.sh).
  • --bundle: If specified, the CLI will bundle the worker’s code (referenced in manifest.bundle.source) into a data: URL within the manifest before deploying. This is useful for deploying workers with local code files.
  • --signer <private-key>: An Ethereum-style private key to sign the work order’s DSSE envelope.

nxcc worker logs

Section titled “nxcc worker logs”

Stream logs from a deployed worker for debugging and monitoring.

nxcc worker logs <worker-id>
  • <worker-id>: The ID of the worker to stream logs from.

Options:

  • --rpc-url <url>: The HTTP RPC URL of the target nXCC node. Defaults to http://localhost:6922.
  • -f, --follow: Follow log output (stream new logs). Defaults to false.
  • -t, --tail <lines>: Number of lines to tail. Defaults to 10.

nxcc node

Section titled “nxcc node”

Commands for interacting with nXCC nodes directly.

nxcc node get-report

Section titled “nxcc node get-report”

Retrieves the node’s environment report, which includes the platform enclave attestation plus other details like the operator signature.

nxcc node get-report

Options:

  • --rpc-url <url>: The HTTP RPC URL of the target nXCC node. Defaults to http://localhost:6922.
  • -o, --output <path>: Output file to save the env report JSON. If not specified, the report is printed to the console.

Examples:

# Print env report to console
nxcc node get-report --rpc-url http://localhost:6922


# Save env report to file
nxcc node get-report --rpc-url http://localhost:6922 -o env-report.json

The environment report contains:

  • attestation: Platform enclave attestation including ephemeral public key, measurements, and block hashes
  • operator_signature: Optional operator signature over the attestation evidence (if configured)

nxcc identity

Section titled “nxcc identity”

Commands for managing on-chain identities. All identity commands require the --gateway-url option which defaults to http://localhost:8545.

nxcc identity create

Section titled “nxcc identity create”

Creates a new identity by minting an ERC-721 NFT to your account.

nxcc identity create <chain> <address> --signer <private-key>
  • <chain>: The chain ID where the Identity contract is deployed (e.g., 31337 for local Anvil).
  • <address>: The address of the deployed Identity.sol contract.

Options:

  • --gateway-url <url>: The RPC URL of the Web3 gateway for the target chain. Defaults to http://localhost:8545 (local Anvil instance).
  • --signer <private-key> (required): The private key of the account that will own the new identity.

nxcc identity set-policy

Section titled “nxcc identity set-policy”

Sets or updates the policy for an existing identity. This updates the tokenURI of the identity NFT.

nxcc identity set-policy <chain> <address> <id> <url-or-path-to-bundle> --signer <private-key>
  • <chain>: The chain ID.
  • <address>: The Identity.sol contract address.
  • <id>: The token ID of the identity to update.
  • <url-or-path-to-bundle>: The URL of the policy or a local path to a policy bundle. If a path is provided, it will be converted to a data: URL.

Options:

  • --gateway-url <url>: The RPC URL of the Web3 gateway. Defaults to http://localhost:8545.
  • --signer <private-key> (required): The private key of the identity’s owner or an approved operator.

nxcc identity get-policy

Section titled “nxcc identity get-policy”

Retrieves the current policy URL for an identity.

nxcc identity get-policy <chain> <address> <id>
  • <chain>: The chain ID.
  • <address>: The Identity.sol contract address.
  • <id>: The token ID of the identity.

Options:

  • --gateway-url <url>: The RPC URL of the Web3 gateway. Defaults to http://localhost:8545.