@ariestools/cli

@ariestools/cli

Aries Tools CLI — a suite by Arie Trouw for AI-client tooling, sandboxed command execution, XL1 datalake provisioning, content hashing (strict + fuzzy + perceptual), XL1 wallet management, payload witnessing, and XYO protocol utilities.

Installation

npm install -g @ariestools/cli
# or
pnpm add -g @ariestools/cli

Quick start

aries --help
aries info
aries hash --algorithm pdq ./photo.jpg
ariesi plex libraries
aries wallet create
aries witness url --url https://example.com
aries datalake list

Local datalake (standalone install)

The published CLI embeds the local datalake dev server. You do not need private monorepo packages (aries-datalake-plane, etc.) installed.

# Isolated state (recommended for CI / Immortalizer)
export ARIES_HOME=/tmp/aries-test-$$

# Free ports by default (or pass --control-port / --plane-port)
aries datalake dev up
aries datalake list
aries datalake dev down

Programmatic client (no shell-out per request)

import {
  createDatalakeClient,
  RestPayloadsClient,
} from '@ariestools/cli/datalake'

// After `aries datalake dev up` (or with baseUrl + authToken options)
const control = createDatalakeClient()
const lakes = await control.list()
// …

Private workspace packages stay private; runtime daemons ship under dist/bin/daemons/ inside this package.

Top-level commands

aries ai           AI client tools
aries bank         Manage bank witness settings
aries chain        Run a local published-chain S3/REST server
aries clamp        Run commands inside a permission-controlled sandbox
aries datalake     Provision and manage on-demand XL1 datalakes
aries hash [file]  Generate a hash (sha256, xyo, fuzzy, perceptual)
aries info         Display version and environment info
aries npmjs        Inspect and lint npmjs org packages
aries pentair      Manage Pentair ScreenLogic systems
ariesi plex        Inspect and manage Plex Media Server (internal build)
aries wallet       XL1 wallet — seed phrases, accounts, transactions, contacts
aries witness      Observe data and produce XYO-compliant payloads
aries xyo          XYO protocol utilities

Global options

Available on every command:

Option	Description
-v, --verbose	Enable verbose output
--version	Show version number
--help	Show help

aries chain — Local published-chain server

# Plain HTTP on loopback (default)
aries chain up

# Locally trusted HTTPS at https://chain.aries.test:8791 (macOS)
brew install mkcert
aries chain up --ssl auto

The server exposes the published-chain buckets at /blocks, /state, and /indexes. --ssl auto keeps the listener on 127.0.0.1, installs or reuses mkcert's local development CA, generates a certificate under ~/.aries/chain/tls, and adds an idempotent chain.aries.test entry to /etc/hosts. The first run may request administrator authorization. The CA and hosts entry remain installed after chain down; chain reset removes the generated Aries certificate files.

Option	Default	Description
--port <number>	8791	Listener port
--host <address>	127.0.0.1	Bind address; auto TLS requires the default
--ssl off|auto	off	Enable macOS automatic local HTTPS setup
--backing memory	memory	Ephemeral storage, wiped on shutdown
--timeout <seconds>	10	Startup health-check timeout

The ready banner prints the S3_ENDPOINT used by ariesi xyo s3 .... Aries automatically selects path-style S3 addressing and trusts the generated CA for the chain.aries.test endpoint. S3_CA_BUNDLE can provide a different private CA file for another HTTPS S3-compatible endpoint.

aries bank — Manage bank witness settings

aries bank capitalone config get
aries bank capitalone config set base-url https://api-sandbox.capitalone.com
aries bank capitalone config set token-url https://api-sandbox.capitalone.com/oauth2/token
aries bank capitalone config set client-id "$CAPITALONE_CLIENT_ID"
aries bank capitalone config set client-secret "$CAPITALONE_CLIENT_SECRET"
aries bank capitalone config set accounts-path /accounts
aries bank capitalone config set balances-path '/accounts/{accountId}/balances'
aries bank capitalone config set transactions-path '/accounts/{accountId}/transactions'

Capital One config is stored in ~/.aries/bank/capitalone.json with restricted file permissions. ARIES_HOME overrides the ~/.aries root.

Capital One U.S. Customer Transactions is a private DevExchange product. Aries therefore requires the endpoint paths supplied by your Capital One partner docs for aries witness bank --resource accounts.

The public sandbox Retrieve Consumer Bank Products product is a deposit product catalog, not personal account data. Use aries witness bank --resource products for that API; Aries uses Capital One's documented sandbox defaults unless you override base-url or token-url.

Capital One config keys

Key	Env var	Default	Description
env	ARIES_CAPITALONE_ENV	sandbox	Environment label: sandbox or production
base-url	ARIES_CAPITALONE_BASE_URL		Capital One API base URL
token-url	ARIES_CAPITALONE_TOKEN_URL		OAuth client-credentials token URL
client-id	ARIES_CAPITALONE_CLIENT_ID		OAuth client id
client-secret	ARIES_CAPITALONE_CLIENT_SECRET		OAuth client secret
scope	ARIES_CAPITALONE_SCOPE		Optional OAuth scope
accounts-path	ARIES_CAPITALONE_ACCOUNTS_PATH		Accounts endpoint path
balances-path	ARIES_CAPITALONE_BALANCES_PATH		Balances endpoint path; may include {accountId}
transactions-path	ARIES_CAPITALONE_TRANSACTIONS_PATH		Transactions endpoint path; may include {accountId}

config get redacts client-secret; pass --show-secrets to print it. Access tokens are not persisted; pass --access-token or set ARIES_CAPITALONE_ACCESS_TOKEN for one run.

aries pentair — Manage Pentair ScreenLogic systems

aries pentair config get
aries pentair config get address
aries pentair config set address 192.0.2.10
aries pentair config set port 80
aries pentair config set system-name "Pentair ScreenLogic"
aries pentair circuit runtime set --circuit-id 6 --hours 24 --on

Pentair config is stored in ~/.aries/pentair/config.json and is used by the Pentair witness and circuit commands. ARIES_HOME overrides the ~/.aries root.

Config keys

Key	Default	Description
address		ScreenLogic adapter IP for direct connection; omit to use UDP discovery
port	80	ScreenLogic adapter TCP port for direct connection
password	SCREENLOGIC_PASSWORD	ScreenLogic password for direct connection
system-name	Pentair ScreenLogic	ScreenLogic system name for direct connection
response-timeout	15000	Milliseconds to wait for each ScreenLogic command response
search-timeout	5000	Milliseconds to wait for each UDP discovery attempt
search-attempts	3	Number of UDP discovery attempts before failing
series-file	~/.aries/pentair/intellichem.jsonl	JSONL file used for saved IntelliChem samples and graphing

config get redacts password; pass --show-secrets to print it.

aries pentair circuit runtime set

Set the ScreenLogic circuit egg timer. Runtime values are sent to ScreenLogic as minutes; --hours 24 becomes 1440.

Option	Description
--circuit-id <id>	Pentair circuit id to update
--hours <n>	Runtime in hours; mutually exclusive with --minutes
--minutes <n>	Runtime in minutes; mutually exclusive with --hours
--on	Turn the circuit on after setting the runtime
--json	Output as JSON

Connection override flags are also accepted: --address, --port, --password, --system-name, --response-timeout, --search-timeout, and --search-attempts.

ariesi plex — Plex Media Server tools

The Plex command is available from the internal ariesi build with license.tier=internal.

ariesi plex libraries

List libraries configured in a Plex Media Server. By default, Aries tries the local server at http://127.0.0.1:32400 and discovers the Plex token from PLEX_TOKEN, X_PLEX_TOKEN, PLEX_AUTH_TOKEN, local Plex .LocalAdminToken, or a local Plex Preferences.xml. If local API auth still blocks access, Aries falls back to the local Plex library database and then Plex Media Scanner --list.

Option	Default	Description
--url <url>	PLEX_URL or http://127.0.0.1:32400	Plex server URL
--token <token>	env/local Preferences.xml	Plex auth token
--preferences <path>	auto-detect	Plex Preferences.xml path for token discovery
--database <path>	auto-detect	Plex library database path for local fallback
--no-fallback		Disable fallback to Plex Media Scanner --list when the API is unavailable
--json	false	Output as JSON

ariesi plex lint [--library <name-or-id>]

Run read-only lint checks against the Plex setup. The first rule, multiple-sources, reports items that have more than one original source media copy. Plex optimized versions and files matching Plex's local extras naming conventions do not count as sources.

Option	Default	Description
-l, --library <name-or-id>	all libraries	Plex library name or ID, e.g. Movies or 9
--database <path>	auto-detect	Plex library database path
--json	false	Output as JSON

ariesi plex items --library <name-or-id>

List top-level items in a Plex library from the local Plex database, including media resolution and optimization details.

Option	Default	Description
-l, --library <name-or-id>	required	Plex library name or ID, e.g. Movies or 9
--database <path>	auto-detect	Plex library database path
--fields <list>	media,optimizations	Comma-separated details: media, optimizations, files, all
--limit <n>		Maximum number of items to inspect
--json	false	Output as JSON

ariesi plex items optimize --tv --library <name-or-id>

Queue Plex "Optimized for TV" versions for items that do not already have one. Aries inspects the local Plex database first, skips items already marked Optimized for TV, and then queues missing items through the local Plex optimizer API.

Option	Default	Description
-l, --library <name-or-id>	required	Plex library name or ID, e.g. Movies or 9
--tv	required	Optimize missing items for Plex's TV profile
--dry-run	false	Show what would be queued without changing Plex
--url <url>	PLEX_URL or http://127.0.0.1:32400	Plex server URL
--token <token>	env/local token discovery	Plex auth token
--preferences <path>	auto-detect	Plex Preferences.xml path for token discovery
--database <path>	auto-detect	Plex library database path
--limit <n>		Maximum number of missing optimizations to queue
--inspect-limit <n>		Maximum number of library items to inspect
--json	false	Output as JSON

ariesi plex items optimize queue [--library <name-or-id>]

List items currently in Plex's optimizer queue. When --library is omitted, Aries lists queued optimizer items across all libraries.

Option	Default	Description
-l, --library <name-or-id>	all libraries	Plex library name or ID, e.g. Movies or 9
--url <url>	PLEX_URL or http://127.0.0.1:32400	Plex server URL
--token <token>	env/local token discovery	Plex auth token
--preferences <path>	auto-detect	Plex Preferences.xml path for token discovery
--database <path>	auto-detect	Plex library database path for library names
--json	false	Output as JSON

aries ai — AI client tools

aries ai detect

Scan for installed AI clients.

Option	Default	Description
--json	false	Output as JSON

aries ai sync

Sync AI config between Claude Code and Codex.

Option	Default	Description
--from <claude|agents>	claude	Source to sync from (the authority)

aries ai lint [path]

Check Claude Code and Codex AI configuration drift. The folder defaults to the current directory.

Option	Default	Description
--scope <all|project|home>	all	Check project config, shared/custom home config, or both
--json	false	Output as JSON

aries clamp — Run commands inside a permission-controlled sandbox

aries clamp run <command> [args..]   # Run a command inside the clamp sandbox
aries clamp policy list              # List available clamp policies
aries clamp policy show <name>       # Show a clamp policy
aries clamp policy init              # Create a starter .aries-clamp.json

Per-command flags

aries clamp run <command> [args..]

Positional		Description
command	required	Command to run inside the sandbox
args	[]	Arguments for the command

Option	Default	Description
-p, --policy <path-or-name>		Policy file path or name
--audit	true	Enable audit logging
--dry-run	false	Show what would be sandboxed without running

aries clamp policy show <name>

Positional		Description
name	required	Policy name or file path

policy list and policy init take no command-specific options.

aries datalake — Provision and manage on-demand XL1 datalakes

Authentication

aries datalake login

Option	Default	Description
--base-url <url>		Control-plane base URL (P0: required)
--token <jwt>		Pre-issued auth token (P0: required; OAuth lands in P1)

aries datalake logout — clears stored credentials, no flags.

Lifecycle

aries datalake create <name>

Positional		Description
name	required	Human-friendly name (unique per owner)

Option	Default	Description
-t, --tier <small|medium|large|archive>	small	Service tier
-s, --size <e.g. 10GB>		Capacity
--iops <n>		Provisioned IOPS target
-r, --region <us-west-2|us-east-1|eu-west-1>		Deployment region
--retention-days <n>	tier default	Retention in days
--verify-hashes	false	Reject inserts whose $hash does not match the content digest
--rate-auth-per-minute <n>		Override: authenticated requests per minute
--rate-anon-per-minute <n>		Override: anonymous requests per minute
--rate-burst-factor <n>		Override: rate-limit burst factor (1 = no burst)

aries datalake list — no flags.

aries datalake describe [name] / aries datalake destroy [name]

Positional		Description
name	active default	Datalake name or id

destroy adds:

Option	Default	Description
-f, --force	false	Required confirmation flag

aries datalake use [name]

Sets the default datalake for subsequent commands. Omit the name to clear.

Access control

aries datalake grant <name> <principal>

Positional		Description
name	required	Datalake name or id
principal	required	User id, or the literal public

Option	Default	Description
-r, --role <viewer|runner>	viewer	Role to grant
--confirm-public	false	Required to grant public runner (anonymous writes)

aries datalake revoke <name> <principal>

Same positionals; no command-specific options.

aries datalake token [name]

Positional		Description
name	active default	Datalake name or id

Option	Default	Description
-r, --role <viewer|runner>	viewer	Role encoded in the token
--ttl <seconds>	server-capped	Lifetime in seconds

Data plane

aries datalake push <file> [name]

Positional		Description
file	required	Path to a .json (array) or .jsonl (one payload/line) file
name	active default	Target datalake

Option	Default	Description
--batch-size <n>	500	Max payloads per HTTP request
--verify	false	Verify each payload's $hash against content locally before pushing
--xl1-sdk	false	Use the real @xyo-network/xl1-protocol-sdk RestDataLakeRunner

aries datalake fetch <hash> [name]

Positional		Description
hash	required	Content hash of the payload
name	active default	Target datalake

Option	Default	Description
--raw	false	Print only the raw JSON payload (no header)
--xl1-sdk	false	Use the real @xyo-network/xl1-protocol-sdk RestDataLakeViewer

aries datalake tail [name]

Positional		Description
name	active default	Datalake name or id

Option	Default	Description
-f, --follow	false	Keep polling for new payloads after draining the backlog
-n, --limit <n>	50	Max payloads per page
--cursor <hash>		Resume after this hash (exclusive)
--schemas <csv>		Comma-separated list of schemas to include
--poll-interval <ms>	1000	Poll interval in ms when following

Audit (data-plane log inspection)

aries datalake audit          # default: view
aries datalake audit view     # Print audit log rows
aries datalake audit purge    # Delete rotated audit files older than --max-age-days

aries datalake audit view

Option	Default	Description
-f, --follow	false	Stream new rows as they arrive (tails the most recent file)
-n, --lines <n>	50	Tail this many rows (0 = start fresh in --follow mode)
--datalake-subject <subject>		Filter by the provider-scoped datalake pseudonym stored in audit rows
--status <prefix>		Status code prefix filter (e.g. 4 matches 4xx)
--method <verb>		HTTP method filter (GET, POST, …)
--authenticated <true|false>		Show only authenticated or only anonymous requests
--grep <regex>		Regex pattern applied to the raw JSON line
--file <path>		File or directory (auto-detects rotation layout)

aries datalake audit purge

Option	Default	Description
--max-age-days <n>	required	Retention window; files older than this are deleted
--directory <path>	<ARIES_HOME>/dev/audit	Rotation directory
--dry-run	false	Report what would be deleted without removing anything

Local development

aries datalake dev up        # Start the local control + data plane dev server
aries datalake dev down      # Stop it (clears credentials)
aries datalake dev status    # Report whether the local dev server is running and healthy
aries datalake dev logs      # Print recent dev server log output
aries datalake dev reset     # Stop the dev server and wipe all local state

aries datalake dev up

Option	Default	Description
--control-port <n>	free loopback port	Control-plane port
--plane-port <n>	free loopback port	Data-plane port
--control-audience <aud>	aries-datalake-control	Exact JWT audience accepted by the control plane
--cors-origin <origin>	disabled	Exact browser origin to allow; repeat for multiple origins
--timeout <s>	10	Seconds to wait for health
--persist	false	Persist store state to disk so it survives restarts
--audit	false	Write a JSONL audit log of every data-plane request
--audit-rotate	false	Rotate the audit log daily (writes to <home>/dev/audit/)
--audit-keep-days <n>		Prune rotated audit files older than this many days

aries datalake dev logs

Option	Default	Description
-f, --follow	false	Stream new lines as they arrive
-n, --lines <n>	50	Number of tail lines to show

down, status, reset take no command-specific options.

ariesi signing-pool — XL1 gas-sponsored transaction signing

Signing pools are wallet-backed servers that co-sign XL1 transactions so the pool address pays gas instead of the caller. The transaction must use signature slot 0 for the pool and signature slot 1 for the caller:

• addresses[0] is the signing-pool address.
• addresses[1] is the authenticated caller address.
• $signatures[0] must be null when submitted.
• $signatures[1] must already verify against addresses[1].

signing-pool sign submits a hydrated transaction tuple [TransactionBoundWitness, payloads[]]. For compatibility with the original CLI helper, the input file may also be an unsigned template; in that case the CLI fills the pool/caller slots, signs slot 1 with the active XL1 wallet, and sends the hydrated tuple to the pool.

ariesi signing-pool create <name> --daily-limit <atto> --max-tx-gas <atto> --min-exp-blocks 10 --max-exp-blocks 500
ariesi signing-pool grant <id> <caller-address>
ariesi signing-pool sign <id> ./tx.json --output ./signed-tx.json
ariesi signing-pool dev up --xl1-node-rpc-url http://127.0.0.1:8545

The control plane rejects transactions it cannot inspect. In this phase, every payload elevated on-chain via script: ["elevate|<payload-hash>"] must be present in the hydrated payload array, and network.xyo.transfer is prohibited as an elevated/on-chain payload.

Local development

ariesi signing-pool dev up      # Start the local signing-pool control plane
ariesi signing-pool dev down    # Stop it
ariesi signing-pool dev status  # Report whether it is running and healthy
ariesi signing-pool dev logs    # Print recent server log output
ariesi signing-pool dev reset   # Stop the server and wipe local state

ariesi signing-pool dev up

Option	Default	Description
--port <n>	8790	Control-plane port
--timeout <s>	10	Seconds to wait for health
--persist	false	Persist pool state under <ARIES_HOME>/signing-pool-dev/store
--audience <aud>	aries-signing-pool	JWT audience accepted by the dev control plane
--master-mnemonic <phrase>	generated	Override the dev mnemonic used to derive pool signing accounts
--xl1-node-rpc-url <url>	$XL1_NODE_RPC_URL	XL1 node RPC URL used to read current block height

The dev client auto-discovers a live local signing-pool state when --base-url, $SIGNING_POOL_CONTROL_URL, and $TOKEN_POOL_CONTROL_URL are not set.

Upstream builder follow-up

The signing pool currently uses a narrow local helper to fill a single $signatures[] slot without mutating the rest of the bound witness. The proper upstream fix belongs in sdk-protocol-js: add explicit partial-signing support to BoundWitnessBuilder, then expose that through TransactionBuilder so a caller can build/sign slot 1 and a signing pool can later sign slot 0 while preserving the hydrated transaction tuple and all existing signatures.

aries hash [file] — content hashing

aries hash [file] [options]
aries hash compare <hashA> <hashB> --algorithm <name> [--json]

Reads input from [file] (positional), --string, or piped stdin (priority order). Dispatches to one of 11 algorithms.

Options

Option	Default	Description
-a, --algorithm <name>	sha256	Algorithm — see the matrix below
-s, --string <text>		Hash this string instead of a file/stdin
-x, --xyo	false	Shortcut for --algorithm xyo (input must be JSON)
--base64	false	Re-encode hex output as base64 (only for hex-output algorithms)
--fps <n>	1	Frames-per-second sample rate (video-frames only)
--frame-algorithm <phash|pdq>	phash	Per-frame hash for video-frames

Algorithm reference

Algorithm	Family	Input	Output	External binary	Compare metric
sha256	strict	bytes	64-char hex	—	exact-match
xyo	strict	JSON	64-char hex	—	exact-match
tlsh	fuzzy-byte	≥50 bytes	70-char hex	—	tlsh-bit-hamming ⚠
nilsimsa	fuzzy-byte	bytes	64-char hex	—	nilsimsa-score
ssdeep	fuzzy-byte	bytes	bs:h1:h2	ssdeep	ssdeep-levenshtein ⚠
phash	perceptual-image	image	16-char hex (64-bit)	—	hamming-64
dhash	perceptual-image	image	16-char hex (64-bit)	—	hamming-64
blockhash	perceptual-image	image	16-char hex (64-bit)	—	hamming-64
pdq	perceptual-image	image	64-char hex (256-bit) — Meta PDQ via WASM	—	hamming-256
chromaprint	audio	audio file	JSON {duration, fingerprint[]}	fpcalc	chromaprint-windowed-hamming
video-frames	video	video file	JSON {fps, frames:[{t,hash}]}	ffmpeg	frame-sequence-<algo>@<fps>fps

⚠ — Approximations, not the canonical reference scores:

• tlsh-bit-hamming — the upstream tlsh npm package only exposes hashing, not the canonical TLSH-diff algorithm. We use bit-level Hamming over the hash body as a proxy.
• ssdeep-levenshtein — block-size-aware Levenshtein, without the canonical block-size attenuation curve.

External binary install

# macOS
brew install ssdeep chromaprint ffmpeg

# Debian/Ubuntu
apt install ssdeep libchromaprint-tools ffmpeg

# Windows
choco install ssdeep chromaprint ffmpeg

Each algorithm probes its binary at hash time and prints clear install instructions if the binary is missing.

Examples

# Strict
aries hash --string "hello"
aries hash ./payload.json --algorithm xyo

# Byte-fuzzy
aries hash --algorithm tlsh ./binary.exe
aries hash compare <hashA> <hashB> --algorithm tlsh

# Perceptual image
aries hash --algorithm phash ./photo.jpg
aries hash --algorithm pdq   ./photo.jpg
aries hash compare <hashA> <hashB> --algorithm pdq

# Audio
aries hash --algorithm chromaprint ./song.mp3 > song.fp.json
aries hash compare "$(cat a.fp.json)" "$(cat b.fp.json)" --algorithm chromaprint --json

# Video
aries hash --algorithm video-frames --fps 1 ./movie.mkv > movie.fp.json
aries hash --algorithm video-frames --fps 1 --frame-algorithm pdq ./movie.mkv > movie-pdq.fp.json
aries hash compare "$(cat a.fp.json)" "$(cat b.fp.json)" --algorithm video-frames

aries hash compare <hashA> <hashB>

Positional		Description
hashA	required	First hash
hashB	required	Second hash

Option	Default	Description
-a, --algorithm <name>	required	Algorithm that produced the hashes
--json	false	Print full result as JSON

Plain output: <similarity>\t<metric>[\tdistance=<n>] (similarity is a 0..1 float, 1 = identical). JSON output: {"similarity":0.93,"distance":18,"metric":"hamming-256"}.

The compare command needs only the two hash strings — works against hashes generated on different machines.

aries npmjs — npmjs org package checks

aries npmjs list --org=xylabs
aries npmjs lint --org=xylabs
aries npmjs lint --org=xylabs --fix
aries npmjs lint              # all auth-visible org packages

By default, package discovery uses your current npm CLI authentication via npm access list packages @<org> --json, so private or restricted org packages are included when your npm account can see them. Omit --org to list or lint all scoped packages returned by npm access list packages --json, grouped by org with a per-org summary at the end. If npm auth is unavailable for a specific --org, aries npmjs falls back to public package discovery and reports npm auth: unauthenticated at the end of text output. Use --public-only with --org to force public discovery.

aries npmjs list

Option	Default	Description
--org <scope>		npm org scope, with or without @; omit for all auth-visible org packages
--public-only	false	List only public packages without using npm access
--json	false	Output as JSON

aries npmjs lint

Find packages that are not marked deprecated but probably should be. V1 reports warning-only findings and exits 0 unless an operational error occurs.

Option	Default	Description
--org <scope>		npm org scope, with or without @; omit for all auth-visible org packages
--public-only	false	Lint only public packages without using npm access
--abandoned-days <n>	365	Warn when latest publish is at least this many days old
--unused-downloads <n>	100	Warn when weekly downloads are below this threshold
--new-days <n>	30	Do not warn for low downloads until a package is at least this many days old
--fix	false	Interactively choose lint findings to deprecate with npm deprecate
--deprecation-message <text>		Message to pass to npm deprecate for selected packages
--json	false	Output as JSON

Rules:

• abandoned — latest publish date is older than the configured threshold.
• unused — weekly downloads are below the configured threshold and the package is not new.

--fix is text-only and prompts with a default Do Nothing / optional Deprecate toggle for each package reported by lint. After selection, each selected package prompts for an optional replacement package name. Blank keeps the default message; a replacement appends Use <replacement> instead. Selected packages are deprecated with npm deprecate <package>@* <message> after Enter is pressed.

aries info

Display ariestools version and environment info. No command-specific options.

aries wallet — XL1 wallet

Wallet commands are provided by the standalone @xyo-network/wallet-xl1-cli package (xl1-wallet). The Aries CLI forwards aries wallet ... to that bin and uses the wallet CLI storage layout: ~/.xl1/wallet/cli by default, overrideable with XL1_WALLET_HOME (ARIES_WALLET_HOME remains a legacy fallback).

Wallet management

aries wallet create               # Generate a new XL1 wallet (random recovery phrase)
aries wallet import               # Import an existing XL1 recovery phrase
aries wallet export               # Print the recovery phrase for the active (or specified) wallet
aries wallet list                 # List stored wallets
aries wallet use <id>             # Set the active wallet
aries wallet rename <id> <label>  # Rename a stored wallet
aries wallet remove <id>          # Delete a stored wallet (and its address book)

aries wallet create

Option	Default	Description
-l, --label <text>	first available wallet#	Friendly label for the wallet
--algorithm <secp256k1|ml-dsa-65>	secp256k1	Wallet signing algorithm

aries wallet import

Option	Default	Description
-l, --label <text>	imported	Friendly label
-p, --phrase <words>		Recovery phrase (skips interactive prompt)
--algorithm <secp256k1|ml-dsa-65>	secp256k1	Wallet signing algorithm

ml-dsa-65 wallets use QuantHDWallet and derive qm65... bech32m addresses. Wallet-JWT commands and datalake --wallet mode require secp256k1 until ML-DSA-65 has a standardized JOSE algorithm. Wallet labels must be unique. If create is run without --label, the CLI uses the first available wallet# label, starting with wallet0.

aries wallet export

Option	Default	Description
--id <wallet-id>	active	Wallet id or label

aries wallet use <id> / aries wallet remove <id>

Positional		Description
id	required	Wallet id or label

aries wallet rename <id> <label>

Positional		Description
id	required	Wallet id or current label
label	required	New label

Session

aries wallet unlock                   # Cache the wallet password (encrypted at rest) for a TTL
aries wallet lock                     # Clear the cached unlocked session
aries wallet password change          # Change the wallet password (re-encrypts every stored phrase)

aries wallet unlock

Option	Default	Description
--ttl <seconds>	900	Session lifetime in seconds (default 15 min)

lock and password change take no command-specific options.

Reset (lost password recovery)

aries wallet reset                    # Destroy all wallet data — only path forward when password is lost

Use this only when you have forgotten your wallet password. There is no other way to recover from a lost password — encrypted seed phrases cannot be decrypted without it.

reset deletes the entire wallet directory (~/.xl1/wallet/cli by default): every stored seed phrase, every derived account, every address-book entry, every saved contact, every saved network configuration, and the active session. This is irreversible unless you have a backup (see aries wallet backup).

To prevent accidental loss, the command requires two interactive confirmations:

• Type the literal word RESET (uppercase, exactly).
• Answer y to the final [y/N] prompt.

Anything else cancels with no changes. There is no --force flag.

If no wallet has been initialized (e.g. on first run), reset is a no-op and prints No wallet found — no reset needed.

Accounts

aries wallet account list                    # List derived accounts in the active wallet
aries wallet account show <offset>           # Show details for a derived account
aries wallet account derive <offset>         # Derive a new account at the given HD offset
aries wallet account label <offset> <label>  # Label a derived account
aries wallet account remove <offset>         # Remove an account from the address book

All account commands take an HD path offset positional (e.g. 0).

aries wallet account derive <offset>

Option	Default	Description
-l, --label <text>		Friendly label for the account

Balance & signing

aries wallet balance [offset]

Positional		Description
offset	0	HD path offset

aries wallet sign <file>

Positional		Description
file	required	Path to a JSON payload file

Option	Default	Description
-o, --offset <n>	0	HD path offset of the signer
-O, --output <path>		Write output to file instead of stdout

Produces a BoundWitness.

Self-signed JWT

A wallet account can mint a JWT-shaped, time-bounded permission token that a site verifies locally, without running its own login flow. Think of it as reverse OAuth: the holder signs an attestation declaring an audience (the domain they intend to use the token at) and an expiration; the site checks the signature and claims and grants the session.

The token is the standard header.payload.signature JWT format, base64url-encoded. The signing input is SHA-256(utf8("${headerB64}.${payloadB64}")) and the alg is ES256K (secp256k1 ECDSA). The header carries both kid (signer address) and pub (full public key) so verification is self-contained — no out-of-band pubkey lookup is needed.

Header fields: alg (ES256K), typ (JWT), kid (40-char lowercase hex address), pub (hex public key bytes).

Payload is an XYO Payload (must include schema). The default schema is network.xyo.auth.signin and the standard claims are iss (mirrors kid), aud, iat, exp, plus optional nbf, nonce, and any extra fields supplied via --payload-file or --claim.

Note: this is the single-signed path. A future co-signed BoundWitness flow (where the site offers a permissions BW signed by its own address and the client co-signs) is planned and will reuse the same schema and account-derivation infrastructure.

aries wallet jwt create

Option	Default	Description
-a, --audience <domain>	required	Audience — becomes the aud claim (e.g. xyo.network)
--ttl <seconds>	3600	Lifetime in seconds (mutually exclusive with --exp)
--exp <unix-seconds>		Absolute expiration; alternative to --ttl
--schema <schema>	network.xyo.auth.signin	XYO schema for the payload
--payload-file <path>		JSON file with extra payload fields (CLI flags win)
--claim <key=value>		Extra claim, repeatable; numeric/boolean strings are coerced
-o, --offset <n>	0	HD path offset of the signer
-O, --output <path>		Write the token to a file instead of stdout

aries wallet jwt verify [token]

Positional		Description
token		JWT to verify (omit to read from --input or stdin)

Option	Default	Description
-a, --audience <domain>		If provided, fail unless aud matches
-i, --input <path>		Read JWT from file
--now <unix-seconds>		Override current time — useful for tests

Prints { ok, header, payload, reasons? } JSON. Exits non-zero on any verification failure (signature, expiry, audience mismatch, kid/iss mismatch, public-key/address mismatch).

aries wallet jwt decode [token]

Decode header and payload without verifying the signature. Useful for debugging.

Transactions

aries wallet send <recipient> <amount>      # Send XL1 to a recipient address
aries wallet tx sign <file>                 # Sign an unsigned transaction JSON file
aries wallet tx broadcast <file>            # Broadcast a signed transaction JSON file

aries wallet send <recipient> <amount>

Positional		Description
recipient	required	Recipient address (0x…)
amount	required	Amount in the selected unit (XL1 by default)

Option	Default	Description
-o, --offset <n>	0	HD path offset of the sender
--xl1		Interpret amount as XL1 (default)
--milli		Interpret amount as milli XL1
--micro		Interpret amount as micro XL1
--nano		Interpret amount as nano XL1
--pico		Interpret amount as pico XL1
--femto		Interpret amount as femto XL1
--atto		Interpret amount as atto XL1; must be a whole number
--dry-run	false	Build and sign the transfer without submitting it
--json	false	Emit machine-readable JSON output
--attempts <n>	30	Confirmation polling attempts
--delay <ms>	2000	Delay between confirmation attempts

aries wallet tx sign <file>

Positional		Description
file	required	Path to unsigned transaction JSON

Option	Default	Description
-o, --offset <n>	0	HD path offset of the signer
-O, --output <path>		Write signed tx to file instead of stdout

aries wallet tx broadcast <file>

Positional		Description
file	required	Path to signed transaction JSON

Option	Default	Description
-o, --offset <n>	0	HD path offset for client connection

Networks

aries wallet network list                # List configured networks
aries wallet network add <id> <rpcUrl>   # Add a custom network
aries wallet network use <id>            # Set the active network
aries wallet network remove <id>         # Remove a custom network

aries wallet network add <id> <rpcUrl>

Positional		Description
id	required	Network id (unique)
rpcUrl	required	Gateway RPC URL

Option	Default	Description
-l, --label <text>		Friendly label
--chain-id <hex>		Chain id (hex)

use and remove take a network id positional only.

Contacts

aries wallet contact list                       # List address-book contacts
aries wallet contact add <address> <label>      # Add or update a contact
aries wallet contact rename <address> <label>   # Rename an existing contact
aries wallet contact remove <address>           # Remove a contact

All take an address positional (0x…); add/rename also take a label positional. No additional flags.

Backup

aries wallet backup export <file>   # Export address books and contacts to a JSON file
aries wallet backup import <file>   # Import a wallet backup JSON file (merges into current state)

file is the only positional; no additional flags.

aries witness — Observe data and produce XYO-compliant payloads

aries witness timestamp     # Capture the current timestamp
aries witness system-info   # Capture system information (OS, CPU, memory, etc.)
aries witness url           # Capture metadata and content from a URL
aries witness bank          # Capture bank account snapshots or Capital One product catalog data
aries witness pentair       # Capture Pentair ScreenLogic pool equipment state
aries witness pentair-intellichem # Capture and graph Pentair IntelliChem chemistry data
aries witness pentair-schedules   # Capture Pentair ScreenLogic schedules with circuit and pump context
aries witness app           # Inspect installed applications
aries witness app list      # List installed macOS applications

Common witness flags

These flags are available on every witness leaf:

Option	Default	Description
--json	false	Output raw JSON
-o, --output <path>		Write output to file
--pretty	true	Pretty-print JSON output
--bound-witness	false	Wrap payloads in a BoundWitness
--binary-dir <path>	~/.aries/binaries/	Directory for binary artifacts

Per-command additions

aries witness url

Option	Default	Description
--url <url>	required	The URL to fetch

aries witness bank

aries witness bank --provider capitalone --account-id acct-123 --from 2026-06-01 --to 2026-06-25 --json
aries witness bank --provider capitalone --access-token "$CAPITALONE_TOKEN" --include-raw --json
aries witness bank --provider capitalone --resource products --client-id "$CAPITALONE_CLIENT_ID" --client-secret "$CAPITALONE_CLIENT_SECRET" --json

Option	Default	Description
--provider <capitalone>	capitalone	Bank provider
--resource <accounts|products>	accounts	accounts for private account APIs; products for Capital One's sandbox deposit product catalog
--from <value>		Transaction window start passed as query param from
--to <value>		Transaction window end passed as query param to
--account-id <id>		Provider account id for balances and transactions
--include-raw	false	Store raw provider JSON as witness binary artifacts
--redaction <default|none>	default	Hash provider account/transaction ids unless explicitly set to none
--env <sandbox|production>	bank config	Environment label
--base-url <url>	bank config	Capital One API base URL
--token-url <url>	bank config	OAuth client-credentials token URL
--access-token <token>	ARIES_CAPITALONE_ACCESS_TOKEN	Pre-issued bearer token; not persisted
--client-id <id>	bank config	OAuth client id
--client-secret <secret>	bank config	OAuth client secret
--scope <scope>	bank config	Optional OAuth client-credentials scope
--api-version <version>	5	Capital One products media-type version
--operation <retrieve-products|retail-products|search>	search	Capital One products operation
--product-id <id>	~ for product-id operations	Capital One path product id
--body <json>	{"isCollapseRate":true} for search; {} otherwise	JSON body for Capital One products POST operations
--body-file <path>		JSON body file for Capital One products POST operations
--accounts-path <path>	bank config	Accounts endpoint path
--balances-path <path>	bank config	Balances endpoint path; may include {accountId}
--transactions-path <path>	bank config	Transactions endpoint path; may include {accountId}

With --resource accounts, the bank witness returns one network.xyo.bank.account-snapshot payload containing normalized accounts, balances, and transactions. By default, provider account and transaction identifiers are hashed.

With --resource products, the bank witness calls Capital One's documented Retrieve Consumer Bank Products sandbox API and returns one network.xyo.bank.product-catalog payload. This is product catalog data, not a consumer account snapshot. The default product request follows Capital One's published "Scenario 1a: All Products" example: POST /deposits/products/~/search with {"isCollapseRate": true}.

If Capital One returns {"id":"200008","text":"no endpoint matched for request"} from the product request after OAuth succeeds, the client credentials are valid but Capital One's sandbox gateway did not match the product endpoint. Verify the app is connected to DevExchange product 1359-5 in the sandbox and confirm the active sandbox base path with Capital One.

aries witness pentair-intellichem

Option	Default	Description
--history	false	Fetch IntelliChem controller history
--from <date|age>	24h	History start as ISO date or relative age like 30m, 6h, 7d
--to <date|age>	now	History end as ISO date or relative age
--save	false	Save normalized samples to the JSONL series file
--series-file <path>	pentair config or ~/.aries/pentair/intellichem.jsonl	JSONL file used for saved samples and graphing
--graph <path>		Write a standalone HTML graph
--graph-only	false	Render a graph from the series file without connecting to ScreenLogic
--address <ip>	pentair config	Connect directly to a ScreenLogic adapter IP instead of UDP discovery
--port <number>	pentair config or 80	ScreenLogic adapter TCP port for direct connection
--password <password>	pentair config or SCREENLOGIC_PASSWORD	ScreenLogic password for direct connection, if configured
--system-name <name>	pentair config or Pentair ScreenLogic	ScreenLogic system name for direct connection
--response-timeout <ms>	pentair config or 15000	Milliseconds to wait for each ScreenLogic command response
--search-timeout <ms>	pentair config or 5000	Milliseconds to wait for each UDP discovery attempt
--search-attempts <count>	pentair config or 3	Number of UDP discovery attempts before failing

Examples:

aries witness pentair-intellichem --save
aries witness pentair-intellichem --history --from 7d --save --graph intellichem.html
aries witness pentair-intellichem --graph-only --graph intellichem.html

aries witness pentair-schedules

Option	Default	Description
--address <ip>	pentair config	Connect directly to a ScreenLogic adapter IP instead of UDP discovery
--port <number>	pentair config or 80	ScreenLogic adapter TCP port for direct connection
--password <password>	pentair config or SCREENLOGIC_PASSWORD	ScreenLogic password for direct connection, if configured
--system-name <name>	pentair config or Pentair ScreenLogic	ScreenLogic system name for direct connection
--response-timeout <ms>	pentair config or 15000	Milliseconds to wait for each ScreenLogic command response
--search-timeout <ms>	pentair config or 5000	Milliseconds to wait for each UDP discovery attempt
--search-attempts <count>	pentair config or 3	Number of UDP discovery attempts before failing

Example:

aries witness pentair-schedules --json

aries witness app list

Option	Default	Description
--scope <all|global|system|user>	all	Filter by install scope

witness timestamp, witness system-info, and witness pentair take only the common flags.

aries xyo — XYO protocol utilities

aries xyo rewards <sequence|mainnet> <view>

Query finalized XL1 reward lifecycle activity (pool funding → step holders → escrows → redemptions) through the SDK REST gateway and its multi-family block rollup indexes (blocks/*).

aries xyo rewards sequence summary
aries xyo rewards mainnet steps --from-block 500000
aries xyo rewards sequence recipients --stage redeemed --limit 25
aries xyo rewards mainnet recipients --stage supplemental-funding --limit 25
aries xyo rewards sequence address <address> --json
aries xyo rewards sequence summary --from-block 510000 --explain
aries xyo rewards sequence index status
aries xyo rewards sequence index verify --concurrency 8

View	Description
summary	Direct and supplemental funding, allocation, payout, actual step-holder balance, unique-recipient, and reward-step totals
steps	Per-step direct funding, supplemental funding, and allocation; optionally filter with --step-level
recipients	Rank recipients at the funded, supplemental-funding, allocated, or redeemed stage
address <address>	Reward lifecycle events involving an escrow, staker, or destination
index status	Show the durable network-stake rewards-index head and its XL1/EVM source-watermark lag
index verify	Recompute cumulative network-stake totals from every immutable reward-step record and verify the snapshot and source hashes

Two different “rewards indexes”. Do not confuse them:

Index	Path / command	What it is for	Used by summary / steps / recipients / address?
Multi-family blocks index	indexes.*.xyo.space blocks/{level}/{i}.json	Bulk block frames for history walks	Yes (via blocksByStep)
Local lifecycle cache	~/.aries/xyo-rewards/<net>/lifecycle/v1/	Client-side cumulative summary resume	Yes (summary only, from-block 0)
Durable network-stake rewards index	rewards/network-stake/v1/{policy}/… + xyo rewards … index	Stake-reward allocation math (XL1 ∩ EVM watermarks)	No — backfilling or verifying it does not speed lifecycle summary

Common option	Default	Description
--from-block <n>	0	First finalized block to include (non-zero → range-delta lifecycle nets)
--to-block <n>	finalized head	Last finalized block to include
--recent-blocks <n>		Scan only the last N blocks (derived from --to-block/head; not with --from-block)
--skip-balance	false	Skip the step-holder balance batch (faster incremental scans; omits outstanding balance)
--lifecycle-cache	true	Summary only: reuse/extend local cumulative cache under ~/.aries/xyo-rewards/<network>/lifecycle/v1/
--refresh-lifecycle-cache	false	Summary only: force a full cumulative rescan and rewrite the local cache
--concurrency <n>	8	Indexed ranges read concurrently, from 1 to 16
--json	false	Stable machine-readable output; XL1 amounts include atto and decimal forms
--explain	false	Show indexed frame use, direct reads, gateway setup/scan/balance requests, bytes, timing, and SDK budget warnings
--no-progress		Suppress the default gateway and scan progress written to stderr

Incremental / recent windows. Full-history mainnet scans are expensive because every finalized block’s transfers are decoded. Prefer a bounded window when you only need recent activity:

aries xyo rewards mainnet summary --recent-blocks 50000 --skip-balance
aries xyo rewards mainnet summary --from-block 900000 --to-block 950000 --skip-balance

With a non-zero start, funding/allocation/escrow nets are range deltas. Step-holder balance (unless --skip-balance) remains the actual balance at --to-block.

Local lifecycle cache (summary). Cumulative summary runs (--from-block 0, no --recent-blocks) persist accumulator state under ~/.aries/xyo-rewards/<network>/lifecycle/v1/head.json. The next run verifies the cached block hash, hydrates unique sets and totals, and only live-scans the tip above the cache watermark. Use --no-lifecycle-cache to disable, or --refresh-lifecycle-cache to rebuild. Cache status appears in --explain and stderr progress. This is a client-side acceleration cache — not the durable network-stake rewards index under rewards/network-stake/....

The initial network-stake rewards-index backfill is an internal S3 mutation and is intentionally excluded from the public aries binary. It builds stake-allocation snapshots under rewards/network-stake/... and does not feed or accelerate summary / steps / recipients / address. Operators run it through ariesi only while the automatic indexer writer is stopped:

ariesi xyo rewards sequence index backfill --dry-run
ariesi xyo rewards sequence index backfill \
  --bucket sequence-index \
  --account-id "$CF_ACCOUNT" \
  --confirm-writer-stopped
aries xyo rewards sequence index verify

backfill resumes from the published rewards head, advances only through the intersection of the durable XL1 index watermark and finalized EVM event-index watermark, and verifies the resulting immutable steps and snapshot directly from S3 before reporting success. --confirm-writer-stopped confirms that the automatic writer is stopped and authorizes writes; --dry-run requires no S3 credentials.

The reward lifecycle distinguishes direct funding (reward pool to step holder) from supplemental funding (any other inbound transfer to a deterministic step holder), followed by allocation (step holder to reward escrow) and redemption (reward escrow to a final wallet). “Total Rewards Funded” is direct plus supplemental funding. “Total Rewards Paid Out” means redeemed rewards. Exact staker identity is visible when an escrow redeems, so uniqueObservedStakers counts stakers seen in redemption context; it is not an allocation-time staker count.

“Outstanding in Step Holders” is the actual sum of deterministic holder account balances at --to-block, read in one SDK batch against the finalized range. The separately reported step-holder lifecycle net is direct plus supplemental funding, minus allocation and rounding returns. With a later --from-block, that lifecycle value and the reward-escrow value are labeled range deltas, while the step-holder balance remains the actual balance at --to-block.

--explain is intentionally part of the product rather than only a debugging flag. It separates gateway startup work from the reward scan and makes direct block fallbacks, payload volume, and repeated request patterns visible. It also reports blocks-index lag (multi-family blocks/* watermark vs chain head): when the blocks index trails the tip, the unfinished range falls back to per-block GETs and full-history scans slow down sharply. Check overall index health with ariesi xyo s3 index monitor mainnet. Those measurements also identify reward-specific lifecycle indexes worth publishing through the XL1 indexing pipeline as full-history use grows.

Human-readable commands print gateway initialization and bounded scan progress to stderr by default. JSON commands remain quiet so stdout stays machine-readable; SDK diagnostics and the completion footer also stay on stderr. Add --verbose to a JSON command to opt into progress.

Every aries and ariesi invocation writes a status-aware timing footer to stderr after the command finishes: ✅ Succeeded in <milliseconds>ms. or ❌ Failed in <milliseconds>ms. This includes JSON commands without changing their machine-readable stdout.

aries xyo tx validate [data]

Validate one or more XL1 transactions. Reads from a file path, inline JSON, or stdin.

Positional		Description
data		Path to a .json/.jsonl file, or an inline transaction JSON tuple [bw, payloads[]]. Omit to read from stdin.

Option	Default	Description
-d, --detail	false	Print per-transaction error details (always shown for invalid transactions)

Input modes (resolved in priority order):

Mode	Example
File path	aries xyo tx validate ./tx.json
File path (JSONL batch)	aries xyo tx validate ./txs.jsonl
Inline JSON	aries xyo tx validate '[[...], [...]]'
Piped stdin	cat txs.jsonl | aries xyo tx validate

Supported file formats:

• .json — a single transaction tuple [boundWitness, payloads[]], or a JSON array of tuples
• .jsonl / .ndjson — one transaction tuple per line

Output:

Total:   3
Valid:   2
Invalid: 1

[2] ./txs.jsonl:3
  - TransactionGasValidator: insufficient gas

Exit codes: 0 = all valid, 1 = any invalid or parse error.

Configuration

Aries configuration lives under ~/.aries/ (or $ARIES_HOME if set). Wallet data lives under ~/.xl1/wallet/cli (or $XL1_WALLET_HOME if set) and is encrypted at rest using your wallet password.

License

LGPL-3.0-only © XY Labs

Credits

Made with 🔥 and ❄️ by AriesTools