Newton CLI

The Newton CLI (newton-cli) is the command-line interface for the Newton Policy Protocol AVS. It provides tools for the full policy lifecycle: uploading policy files to IPFS, deploying policy data and policy contracts, managing policy client registration, configuring runtime parameters, submitting evaluation requests, checking version compatibility, and running local Rego simulations.

Installation

Build from source:

cargo build --bin newton-cli --release

The binary is placed at target/release/newton-cli.

Global Flags

Every command accepts these top-level flags:

Flag	Env Var	Description
`--chain-id <ID>`	`CHAIN_ID`	Target chain ID (e.g., `11155111` for Sepolia)
`--config-path <PATH>`	-	Path to CLI config file (default: `~/.newton/newton-cli.toml`)
`--log-format <FMT>`	-	Log format: `full`, `compact`, `pretty`, `json`, or `minimal`
`--quiet`	-	Suppress all log output

Configuration

Config File

The CLI loads configuration from ~/.newton/newton-cli.toml (or the path given by --config-path). The config file provides:

eth_rpc_url - Default Ethereum RPC endpoint
gateway_url - Newton Gateway URL for task submission
signer - ECDSA signing key configuration

Some commands (policy-files, policy-client, regorus) work without a config file. Commands that interact with the protocol (task, policy, policy-data) require one.

Environment Variables

Most commands support configuration via environment variables. Create a .env file in your working directory:

CHAIN_ID=11155111
PRIVATE_KEY="0x..."
RPC_URL="https://eth-sepolia.g.alchemy.com/v2/your-api-key"
PINATA_JWT="your-pinata-jwt"
PINATA_GATEWAY="your-gateway.mypinata.cloud"
DEPLOYMENT_ENV="stagef"   # "stagef" or "prod" (default: "prod")

CLI arguments always take precedence over environment variables.

Commands

policy-files

Manages policy file uploads to IPFS via Pinata. This is typically the first step in setting up a new policy.

generate-cids

Uploads all policy files to Pinata IPFS and writes a policy_cids.json manifest containing the resulting CIDs.

Files uploaded (from --directory):

policy.wasm - Compiled WASM data provider
policy.rego - Rego policy rules
params_schema.json - Policy parameter schema
policy_metadata.json - Policy metadata
policy_data_metadata.json - Policy data metadata

newton-cli --chain-id 11155111 policy-files generate-cids \
    --directory policy-files \
    --output policy-files/policy_cids.json \
    --pinata-jwt "$PINATA_JWT" \
    --pinata-gateway "$PINATA_GATEWAY" \
    --entrypoint "max_gas_price.allow"

Argument	Required	Default	Description
`--directory`	No	`policy-files`	Directory containing policy files
`--entrypoint`	Yes	-	Rego entrypoint rule (e.g., `max_gas_price.allow`)
`--pinata-jwt`	Yes	env `PINATA_JWT`	Pinata API JWT token
`--pinata-gateway`	Yes	env `PINATA_GATEWAY`	Pinata gateway domain
`--output`	No	`policy-files/policy_cids.json`	Output path for CID manifest

The output policy_cids.json is used as input to policy-data deploy and policy deploy.

policy-data

Manages policy data contracts that store WASM CIDs, attestation configuration, and expiration settings on-chain.

deploy

Deploys a new policy data contract. Reads CIDs from policy_cids.json, deploys the contract, and sets attestation info (ECDSA type with configured attesters including all known task generator addresses).

The expire_after value is automatically converted from 300 seconds to blocks based on the target chain's block time.

newton-cli --chain-id 11155111 policy-data deploy \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL" \
    --policy-cids policy-files/policy_cids.json

Argument	Required	Default	Description
`--private-key`	Yes	env `PRIVATE_KEY`	Deployer private key
`--rpc-url`	Yes	env `RPC_URL`	RPC endpoint URL
`--policy-cids`	No	`policy-files/policy_cids.json`	Path to CID manifest

simulate

Executes the WASM data provider locally without deploying to the blockchain. Useful for testing WASM logic before deployment.

newton-cli --chain-id 11155111 policy-data simulate \
    --wasm-file policy-files/policy.wasm \
    --input-json '{}'

Argument	Required	Description
`--wasm-file`	Yes	Path to WASM component file
`--input-json`	Yes	Input JSON string for WASM execution

policy

Manages policy contracts that define authorization rules via Rego policies.

deploy

Deploys a new policy contract referencing a previously deployed policy data contract. Reads policy CIDs from the manifest and links to the specified policy data address.

newton-cli --chain-id 11155111 policy deploy \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL" \
    --policy-cids policy-files/policy_cids.json \
    --policy-data-address "0xdB9578b6c719122ECd30667D84D1fb483c789BC8"

Argument	Required	Default	Description
`--private-key`	Yes	env `PRIVATE_KEY`	Deployer private key
`--rpc-url`	Yes	env `RPC_URL`	RPC endpoint URL
`--policy-cids`	Yes	-	Path to CID manifest
`--policy-data-address`	Yes	-	Deployed policy data contract address

simulate

Runs a full local policy evaluation: executes the WASM data provider, then evaluates the Rego policy against a provided intent. No blockchain interaction required.

newton-cli --chain-id 11155111 policy simulate \
    --wasm-file policy-files/policy.wasm \
    --rego-file policy-files/policy.rego \
    --intent-json policy-files/intent.json \
    --entrypoint "max_gas_price.allow" \
    --wasm-args policy-files/wasm_args.json \
    --policy-params-data policy-files/policy_params_data.json

Argument	Required	Default	Description
`--wasm-file`	Yes	-	Path to WASM component file
`--rego-file`	Yes	-	Path to Rego policy file
`--intent-json`	Yes	-	Path to intent JSON file
`--entrypoint`	No	`allow`	Rego entrypoint rule
`--wasm-args`	No	`{}`	Path to JSON arguments for WASM execution
`--policy-params-data`	No	`{}`	Path to JSON policy parameters

Notes:

The data. prefix is automatically added to the entrypoint if not present.
Intent fields value and chainId are normalized to decimal number strings (hex and numeric formats accepted).

policy-client

Manages policy client contracts and their registration in the PolicyClientRegistry. Policy clients must be registered before they can be used with the IdentityRegistry.

register

Registers a policy client with the PolicyClientRegistry. The caller becomes the registered owner. The contract validates ERC-165 interface conformance at registration time.

newton-cli policy-client register \
    --registry "0x..." \
    --client "0x..." \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

deactivate

Deactivates a registered policy client. Only callable by the registered owner. Deactivated clients are rejected by IdentityRegistry._linkIdentity().

newton-cli policy-client deactivate \
    --registry "0x..." \
    --client "0x..." \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

activate

Reactivates a previously deactivated policy client. Only callable by the registered owner.

newton-cli policy-client activate \
    --registry "0x..." \
    --client "0x..." \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

transfer-ownership

Transfers the registry ownership record of a policy client to a new address. Only callable by the current owner.

newton-cli policy-client transfer-ownership \
    --registry "0x..." \
    --client "0x..." \
    --new-owner "0x..." \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

status

Queries the registration status and record for a policy client. Read-only (no private key required).

newton-cli policy-client status \
    --registry "0x..." \
    --client "0x..." \
    --rpc-url "$RPC_URL"

Output:

Client: 0x...
  Owner: 0x...
  Active: true
  Registered At: 1234567890 (unix timestamp)
  isRegisteredClient: true

list

Lists all policy clients owned by an address. Read-only.

newton-cli policy-client list \
    --registry "0x..." \
    --owner "0x..." \
    --rpc-url "$RPC_URL"

set-policy

Sets the policy contract address on a policy client. This is the owner-only setPolicyAddress() function used to point a policy client at a new or migrated policy.

newton-cli policy-client set-policy \
    --client "0x..." \
    --policy "0x..." \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

set-policy-params

Sets runtime policy parameters and expiration on a policy client contract.

newton-cli policy-client set-policy-params \
    --policy-client "0x..." \
    --policy-params policy-files/policy_params_data.json \
    --expire-after 1000 \
    --private-key "$PRIVATE_KEY" \
    --rpc-url "$RPC_URL"

Argument	Required	Description
`--policy-client`	Yes	Policy client contract address
`--policy-params`	Yes	Path to JSON file containing policy parameters
`--expire-after`	Yes	Expiration period in blocks
`--private-key`	Yes	Owner private key (env: `PRIVATE_KEY`)
`--rpc-url`	Yes	RPC endpoint URL (env: `RPC_URL`)

Registry subcommand arguments:

All registry write operations (register, deactivate, activate) share:

Argument	Required	Description
`--registry`	Yes	PolicyClientRegistry contract address
`--client`	Yes	Policy client contract address
`--private-key`	Yes	Transaction signer key (env: `PRIVATE_KEY`)
`--rpc-url`	Yes	RPC endpoint URL (env: `RPC_URL`)

task

Commands for submitting policy evaluation requests to the Newton Prover AVS.

submit-evaluation-request

Signs and submits a task for policy evaluation. The command normalizes the intent (converts value/chainId to hex), signs the task with the provided private key, and submits it to the gateway via JSON-RPC (newt_createTask).

newton-cli --chain-id 11155111 task submit-evaluation-request \
    --task-json path/to/task.json \
    --private-key "$PRIVATE_KEY"

Argument	Required	Default	Description
`--task-json`	Yes	-	Path to task JSON file
`--private-key`	Yes	env `PRIVATE_KEY`	Signer private key
`--api-key`	No	-	API key for gateway authentication

Task JSON format:

{
  "policyClient": "0x...",
  "intent": {
    "sender": "0x...",
    "to": "0x...",
    "value": "1000000000000000000",
    "chainId": "11155111",
    "data": "0x..."
  },
  "quorumNumber": 0,
  "quorumThresholdPercentage": 67,
  "wasmArgs": {},
  "timeout": 30
}

Fields quorumNumber, quorumThresholdPercentage, wasmArgs are optional.

Gateway URL resolution: The gateway URL is determined by DEPLOYMENT_ENV (default: prod) and the chain ID. Valid values for DEPLOYMENT_ENV are stagef and prod.

version

Commands for checking protocol version compatibility and migrating policy clients to newer factory versions.

check-compatibility

Checks whether a policy client's policy and policy data contracts were deployed by compatible factory versions. Outputs a JSON compatibility report.

newton-cli version check-compatibility \
    --policy-client "0x..." \
    --chain-id 11155111 \
    --rpc-url "$RPC_URL"

Argument	Required	Description
`--policy-client`	Yes	Policy client contract address
`--chain-id`	Yes	Target chain ID
`--rpc-url`	No	RPC endpoint (falls back to config)

Exits with code 1 if migration is required.

migrate

Automatically migrates a policy client to the latest compatible factory version. The migration:

Checks current compatibility (unless --skip-check)
Reads current policy configuration from chain
Redeploys incompatible policy data contracts with the latest factory
Deploys a new policy with the latest factory, reusing compatible policy data
Updates the policy client to point to the new policy via setPolicyAddress()
Verifies the migration succeeded

newton-cli version migrate \
    --policy-client "0x..." \
    --private-key "$PRIVATE_KEY" \
    --chain-id 11155111 \
    --rpc-url "$RPC_URL"

Argument	Required	Default	Description
`--policy-client`	Yes	-	Policy client to migrate
`--private-key`	Yes	env `PRIVATE_KEY`	Owner private key
`--chain-id`	Yes	-	Target chain ID
`--rpc-url`	No	from config	RPC endpoint URL
`--skip-check`	No	`false`	Skip initial compatibility check
`--dry-run`	No	`false`	Preview migration without executing

Use --dry-run first to preview what changes will be made.

info

Displays protocol version information including the current version and minimum compatible version.

newton-cli version info

regorus

Wraps the Regorus Rego policy engine with Newton-specific crypto extensions (newton.crypto.* builtins). Useful for local policy development and debugging.

eval

Evaluates a Rego query with Newton extensions enabled.

newton-cli regorus eval \
    -b ./policies \
    -d data.json \
    -i input.json \
    "data.auth.allowed"

Argument	Required	Description
`-b/--bundles`	No	Directories containing Rego files
`-d/--data`	No	Policy or data files (`.rego`, `.json`, `.yaml`)
`-i/--input`	No	Input file (`.json` or `.yaml`)
`query`	Yes	Rego query expression
`-t/--trace`	No	Enable execution tracing
`-n/--non-strict`	No	Non-strict mode (OPA-compatible)
`-c/--coverage`	No	Display coverage information

lex

Tokenizes a Rego policy file.

newton-cli regorus lex policy.rego [-v]

parse

Parses a Rego policy file and prints the parsed structure.

newton-cli regorus parse policy.rego

ast

Parses a Rego policy and dumps the AST as JSON.

newton-cli regorus ast policy.rego

Typical Workflow

A complete policy deployment workflow follows these steps:

1. Upload policy files to IPFS
   newton-cli policy-files generate-cids ...

2. Deploy policy data contract
   newton-cli policy-data deploy ...

3. Deploy policy contract (referencing policy data)
   newton-cli policy deploy ...

4. Register the policy client with the registry
   newton-cli policy-client register ...

5. Set the policy address on the policy client
   newton-cli policy-client set-policy ...

6. Configure runtime parameters
   newton-cli policy-client set-policy-params ...

7. Submit evaluation requests
   newton-cli task submit-evaluation-request ...

Testing Policies Locally

Before deploying, test your policy logic locally:

# Test WASM data provider in isolation
newton-cli policy-data simulate \
    --wasm-file policy-files/policy.wasm \
    --input-json '{}'

# Test full policy evaluation (WASM + Rego)
newton-cli policy simulate \
    --wasm-file policy-files/policy.wasm \
    --rego-file policy-files/policy.rego \
    --intent-json policy-files/intent.json \
    --entrypoint "max_gas_price.allow"

# Debug Rego rules with the regorus engine
newton-cli regorus eval \
    -d policy-files/policy.rego \
    -i input.json \
    "data.max_gas_price.allow"

newton-cli 0.1.33

Newton CLI

Installation

Global Flags

Configuration

Config File

Environment Variables

Commands

policy-files

generate-cids

policy-data

deploy

simulate

policy

deploy

simulate

policy-client

register

deactivate

activate

transfer-ownership

status

list

set-policy

set-policy-params

task

submit-evaluation-request

version

check-compatibility

migrate

info

regorus

eval

lex

parse

ast

Typical Workflow

Testing Policies Locally

Related Documentation