cli reference

Complete reference for the canaad command-line tool. Install with:

cargo install canaad-cli

Input sources

All three subcommands accept input in the same way, checked in this order:

  1. Positional argument — inline JSON string
  2. -f / --file — read from a file path (conflicts with positional)
  3. Piped stdin — auto-detected; interactive terminal input is rejected with an error
# inline
canaad canonicalize '{"v":1,"tenant":"acme","resource":"/doc/123","purpose":"encrypt"}'

# from file
canaad canonicalize -f input.json

# piped stdin
echo '{"v":1,"tenant":"acme","resource":"/doc/123","purpose":"encrypt"}' | canaad canonicalize

canonicalize

Canonicalizes AAD JSON to deterministic bytes per RFC 8785.

canaad canonicalize [INPUT] [OPTIONS]

Options

Flag Short Default Description
--file <PATH> -f — Read input from file
--output <FORMAT> -o utf8 Output format: utf8, hex, base64, raw
--to-file <PATH> — — Write output to file instead of stdout

Output formats

Format Behavior
utf8 Canonical JSON as a UTF-8 string, followed by a newline. Default.
hex Hex-encoded canonical bytes, followed by a newline.
base64 Base64-encoded canonical bytes (standard alphabet), followed by a newline.
raw Raw binary bytes. No trailing newline. Best for piping to other tools or --to-file.

Examples

canaad canonicalize -f input.json                    # utf8 to stdout
canaad canonicalize -f input.json -o hex              # hex to stdout
canaad canonicalize -f input.json -o raw --to-file output.bin   # raw bytes to file

validate

Validates AAD JSON structure and field constraints against the spec. Does not produce canonical output.

canaad validate [INPUT] [OPTIONS]

Options

Flag Short Default Description
--file <PATH> -f — Read input from file
--quiet -q false Suppress "valid" message; exit code only

Behavior

  • On success: prints valid to stdout (unless --quiet), exits 0.
  • On failure: prints error to stderr, exits 1.

Examples

canaad validate -f input.json              # prints "valid" or error
canaad validate -f input.json --quiet      # silent; check $?
canaad validate -f input.json -q && echo ok || echo fail

hash

Computes the SHA-256 hash of the canonical AAD form.

canaad hash [INPUT] [OPTIONS]

Options

Flag Short Default Description
--file <PATH> -f — Read input from file
--output <FORMAT> -o hex Output format: hex, base64

Note: The hash command defaults to hex, while canonicalize defaults to utf8.

Examples

canaad hash -f input.json                  # hex-encoded SHA-256
canaad hash -f input.json -o base64        # base64-encoded SHA-256

Exit codes

Code Meaning Cause
0 Success Command completed normally
1 Validation error Malformed JSON, schema violation, or AAD constraint failure
2 I/O error Unreadable file, stdin failure, write failure

Exit code classification: any error containing an AadError in the chain is treated as a validation error (1); everything else is I/O (2). All errors print to stderr.

Global flags

Flag Description
--version Print version and exit
--help Print help for the tool or any subcommand 
canaad --version
canaad canonicalize --help