Skip to content

CLI Reference

The axl command-line tool ships with axl-core. All five commands are documented below.

Installation

pip install axl-core

The axl binary is added to your PATH automatically.

Commands

axl parse

Parse a raw AXL packet and display its structure.

axl parse "S:OPS.3|cpu_high|node-7|threshold=90|!ALERT|!ROUTE"

Output:

Packet
  Header
    Domain: OPS
    Tier:   3
  Fields
    [0] cpu_high
    [1] node-7
    [2] threshold=90
  Flags
    [0] ALERT
    [1] ROUTE

With preamble elements:

axl parse "@ipfs://Qm.../rosetta.axl|T:1711234567|S:SIG.2|breach|zone-3|!ALERT"

Output:

Packet
  Preamble
    Rosetta:   ipfs://Qm.../rosetta.axl
    Timestamp: 1711234567
  Header
    Domain: SIG
    Tier:   2
  Fields
    [0] breach
    [1] zone-3
  Flags
    [0] ALERT

axl validate

Validate a packet for syntactic and semantic correctness.

axl validate "S:OPS.3|cpu_high|node-7|!ALERT"

Output:

Valid: true
Domain: OPS
Tier: 3
Errors: []
Warnings: []

Invalid packet:

axl validate "S:BOGUS.99|bad_field"

Output:

Valid: false
Domain: BOGUS
Tier: 99
Errors:
  - Unknown domain: BOGUS
  - Tier out of range: 99 (must be 1-5)
Warnings: []

With strict mode:

axl validate --strict "S:OPS.3|cpu_high|!CUSTOM_FLAG"

Output:

Valid: false
Domain: OPS
Tier: 3
Errors:
  - Unknown flag in strict mode: CUSTOM_FLAG
Warnings: []

axl translate

Translate an AXL packet to English or JSON.

Translate to English

axl translate --to english "S:SIG.1|breach_detected|zone-4|severity=critical|!ALERT|!ESCALATE"

Output:

Security signal (priority 1): Breach detected in zone-4, severity critical.
Flags: ALERT, ESCALATE.

Translate to JSON

axl translate --to json "S:OPS.3|cpu_high|node-7|threshold=90|!ALERT"

Output:

{
  "domain": "OPS",
  "tier": 3,
  "fields": [
    "cpu_high",
    "node-7",
    "threshold=90"
  ],
  "flags": [
    "ALERT"
  ],
  "timestamp": null,
  "rosetta": null,
  "payment": null
}

axl emit

Construct and emit a new AXL packet from parameters.

axl emit --domain SIG --tier 3 --fields "intrusion_detected,sector-4,confidence=0.97" --flags "ALERT,ESCALATE"

Output:

S:SIG.3|intrusion_detected|sector-4|confidence=0.97|!ALERT|!ESCALATE

With timestamp and nonce:

axl emit --domain OPS --tier 2 --fields "deploy_complete,service=api-v3" --flags "ACK,LOG" --timestamp --nonce

Output:

T:1711234567|N:42|S:OPS.2|deploy_complete|service=api-v3|!ACK|!LOG

With payment proof:

axl emit --domain PAY --tier 1 --fields "invoice_settled,amount=500,currency=USDC" --flags "ACK" --payment "0xabc123:sig_def456:21000"

Output:

π:0xabc123:sig_def456:21000|S:PAY.1|invoice_settled|amount=500|currency=USDC|!ACK

axl version

Print the installed version.

axl version

Output:

axl-core 0.4.2

Exit Codes

Code Meaning
0 Success
1 Invalid packet / parse error
2 Validation failure
3 Unknown command or flag

Environment Variables

Variable Description Default
AXL_STRICT Enable strict validation globally false
AXL_OUTPUT Default output format (text/json) text
AXL_NO_COLOR Disable colored terminal output false