# 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:
```bash
cargo build --bin newton-cli --release
```
The binary is placed at `target/release/newton-cli`.
## Global Flags
Every command accepts these top-level flags:
| `--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:
```bash
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
```bash
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"
```
| `--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.
```bash
newton-cli --chain-id 11155111 policy-data deploy \
--private-key "$PRIVATE_KEY" \
--rpc-url "$RPC_URL" \
--policy-cids policy-files/policy_cids.json
```
| `--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.
```bash
newton-cli --chain-id 11155111 policy-data simulate \
--wasm-file policy-files/policy.wasm \
--input-json '{}'
```
| `--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.
```bash
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"
```
| `--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.
```bash
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
```
| `--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.
```bash
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()`.
```bash
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.
```bash
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.
```bash
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).
```bash
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.
```bash
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.
```bash
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.
```bash
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"
```
| `--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:
| `--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`).
```bash
newton-cli --chain-id 11155111 task submit-evaluation-request \
--task-json path/to/task.json \
--private-key "$PRIVATE_KEY"
```
| `--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:**
```json
{
"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.
```bash
newton-cli version check-compatibility \
--policy-client "0x..." \
--chain-id 11155111 \
--rpc-url "$RPC_URL"
```
| `--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:
1. Checks current compatibility (unless `--skip-check`)
2. Reads current policy configuration from chain
3. Redeploys incompatible policy data contracts with the latest factory
4. Deploys a new policy with the latest factory, reusing compatible policy data
5. Updates the policy client to point to the new policy via `setPolicyAddress()`
6. Verifies the migration succeeded
```bash
newton-cli version migrate \
--policy-client "0x..." \
--private-key "$PRIVATE_KEY" \
--chain-id 11155111 \
--rpc-url "$RPC_URL"
```
| `--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.
```bash
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.
```bash
newton-cli regorus eval \
-b ./policies \
-d data.json \
-i input.json \
"data.auth.allowed"
```
| `-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.
```bash
newton-cli regorus lex policy.rego [-v]
```
#### parse
Parses a Rego policy file and prints the parsed structure.
```bash
newton-cli regorus parse policy.rego
```
#### ast
Parses a Rego policy and dumps the AST as JSON.
```bash
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:
```bash
# 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"
```
## Related Documentation
- [Policy Client Integration Guide](../../docs/POLICY_CLIENT_GUIDE.md)
- [Version Management](../../docs/VERSIONING.md)
- [Regorus Extensions](../../docs/REGORUS_DEVELOPMENT.md)
- [Architecture Overview](../../docs/ARCHITECTURE.md)
- [Commands Overview](src/commands/README.md)
- [Test Suite](tests/README.md)