@xylabs/aries

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

Installation

npm install -g @xylabs/aries
# or
pnpm add -g @xylabs/aries

Quick start

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

Top-level commands

aries ai           AI client tools
aries audit        Manage the Claude Code audit trail
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 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 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 audit — Manage the Claude Code audit trail

aries audit ai                    # Show current AI metadata recorded in audit entries
aries audit list                  # List audit sessions
aries audit show <session-id>     # Show audit trail for a session
aries audit search <query>        # Search audit logs
aries audit install [provider]    # Install the audit plugin (claude | codex | both)
aries audit uninstall [provider]  # Uninstall the audit plugin
aries audit open                  # Open the audit log directory in Finder/Explorer
aries audit status                # Show audit plugin status and log statistics

Per-command flags

aries audit ai

| Option | Default | Description | |---|---|---| | --json | false | Output as JSON |

aries audit list

| Option | Default | Description | |---|---|---| | -d, --date <YYYY-MM-DD> | | Filter by date |

aries audit show <session-id>

| Positional | | Description | |---|---|---| | session-id | required | Session ID (or prefix) |

| Option | Default | Description | |---|---|---| | -f, --format <text\|json> | text | Output format |

aries audit search <query>

| Positional | | Description | |---|---|---| | query | required | Search text |

| Option | Default | Description | |---|---|---| | -d, --date <YYYY-MM-DD> | | Filter by date | | -n, --limit <n> | 50 | Max results |

aries audit install [provider] / aries audit uninstall [provider]

| Positional | | Description | |---|---|---| | provider | both | claude or codex |

open, status take no command-specific options.

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) | | -d, --datalake <id> | | Filter by datalake name or id | | --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> | 8787 | Control-plane port | | --plane-port <n> | 8788 | Data-plane port | | --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.

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 info

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

aries wallet — XL1 wallet

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> | primary | Friendly label for the wallet |

aries wallet import

| Option | Default | Description | |---|---|---| | -l, --label <text> | imported | Friendly label | | -p, --phrase <words> | | Recovery phrase (skips interactive prompt) |

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.

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.

Transactions

aries wallet tx send <recipient> <amount>   # Build, sign, and broadcast an XL1 transfer
aries wallet tx sign <file>                 # Sign an unsigned transaction JSON file
aries wallet tx broadcast <file>            # Broadcast a signed transaction JSON file

aries wallet tx send <recipient> <amount>

| Positional | | Description | |---|---|---| | recipient | required | Recipient address (0x…) | | amount | required | Amount in whole XL1 |

| Option | Default | Description | |---|---|---| | -o, --offset <n> | 0 | HD path offset of the sender | | --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 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 app list

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

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

aries xyo — XYO protocol utilities

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

All persistent configuration lives under ~/.aries/ (or $ARIES_HOME if set). Wallet data is encrypted at rest using your wallet password.

License

LGPL-3.0-only © XY Labs