OpenETR CLI Implementation Walkthrough¶
This note connects the current OpenETR specifications to the reference CLI behavior.
It is not a separate protocol specification. It is a practical map from the current specs to the commands and event shapes implemented by the CLI.
Status¶
Draft, reflecting the current openetr CLI implementation.
Spec-To-Implementation Map¶
The current CLI implements the Nostr wire model described in OPENETR_NOSTR_WIRE_FORMAT_SPEC.md.
At a high level:
openetr issuepublishes akind 1415Anchor Eventopenetr transfer initiatepublishes akind 1416event withaction=initiateopenetr transfer acceptpublishes akind 1416event withaction=acceptopenetr terminate-etrpublishes akind 1416event withaction=terminateopenetr attestpublishes akind 1416event withaction=attestopenetr encumberpublishes akind 1416event withaction=encumberopenetr dischargepublishes akind 1416event withaction=dischargeopenetr redeempublishes akind 1416event withaction=redeemopenetr queryqueries the Anchor Event and Evidence Event families and derives the current object state
The older openetr issue-etr and openetr query-etr command names remain available as compatibility aliases for ETR-focused workflows and existing scripts.
The implementation constants for these actions live in openetr/control.py.
Identity Setup¶
The CLI uses the root/profile model described in ROOT_AND_PROFILE_IDENTITY_MODEL.md.
Create or update a profile with relay and query defaults:
openetr profile set warehouse \
--relays wss://relay.openetr.org \
--kind 1415 \
--query-timeout 10 \
--publish-wait 2.0 \
--limit 20 \
--query-output full
Publish the public profile metadata:
openetr profile publish \
--profile warehouse \
--name "Delhi Warehouse" \
--display-name "Warehouse" \
--about "Warehouse custodian profile" \
--address "123 Startop Way, Delhi, India" \
--force
Use the profile as the active signer:
openetr profile use warehouse
openetr whoami
Inspect the root administrative identity and controlled profiles:
openetr root
Issue An Object¶
Issue a digital artifact from a local file:
openetr issue examples/MLWR001.pdf
Implementation mapping:
- event kind:
1415 otag: object digest hex- signer: active profile signer unless overridden
- object digest: SHA-256 of the source file
The same command can be used with other files, such as:
openetr issue examples/ebl6.md
Query Object State¶
Query the current state and control history:
openetr query examples/MLWR001.pdf
The query command resolves:
- the initial Anchor Event
- matching
kind 1416evidence events - evidence-event chains linked by
etags - lifecycle state, including active, redemption-pending, or terminated
- current controller
- profiles for relevant signers and participants where available
- encumbrance summary, including outstanding and discharged encumbrances
This is the main CLI surface for verifying the effect of the event shapes described in the wire-format and evidence-event specs.
Transfer Control¶
Initiate a transfer from the current controller to another profile:
openetr transfer initiate examples/MLWR001.pdf --transferee exporter
Implementation mapping:
- event kind:
1416 action:initiated:<object_hex>:initiateo:<object_hex>e: prior Anchor Event or Evidence Event idp: transferee pubkey
The transferee accepts after switching profiles:
openetr profile use exporter
openetr transfer accept examples/MLWR001.pdf
Implementation mapping:
- event kind:
1416 action:acceptd:<object_hex>:accepto:<object_hex>e: transfer initiate event id or prior evidence event id selected by the implementation
The query output should then show the exporter as the current controller if the local recognition logic accepts the transfer chain.
Encumber And Discharge¶
Declare an encumbrance in favor of a beneficiary profile:
openetr encumber examples/MLWR001.pdf \
--beneficiary lender \
--type pledge \
--ref encumbrance-MLWR001-001
Implementation mapping:
- event kind:
1416 action:encumberd:<object_hex>:encumbero:<object_hex>e: prior Anchor Event or Evidence Event idp: beneficiary or secured-party pubkey- optional
type: encumbrance subtype, such aspledge - optional
ref: external reference
Discharge a specific encumbrance by referencing the encumbrance event id:
openetr discharge examples/MLWR001.pdf \
--encumbrance-event <encumbrance_event_id_or_nevent> \
--releasing-party lender \
--ref discharge-MLWR001-001
Implementation mapping:
- event kind:
1416 action:discharged:<object_hex>:dischargeo:<object_hex>e: prior Anchor Event or Evidence Event idenc: encumbrance event id being discharged- optional
p: beneficiary or releasing-party pubkey - optional
ref: external reference
openetr query-etr reports encumbrances as:
- total encumbrances
- discharged encumbrances
- outstanding encumbrances
- detail for each outstanding encumbrance, including beneficiary, type, and ref where present
Redeem And Terminate¶
Record presentation to an obligor:
openetr redeem examples/MLWR001.pdf \
--obligor warehouse \
--ref redemption-MLWR001-001
Implementation mapping:
- event kind:
1416 action:redeemd:<object_hex>:redeemo:<object_hex>e: prior Anchor Event or Evidence Event idp: obligor pubkey- optional
ref: external reference
The reference query logic treats redeem as moving the object into a redemption-pending lifecycle state.
Terminate the active lifecycle:
openetr terminate-etr examples/MLWR001.pdf
Implementation mapping:
- event kind:
1416 action:terminated:<object_hex>:terminateo:<object_hex>e: prior Anchor Event or Evidence Event id
The reference query logic treats terminate as ending the active lifecycle when recognized.
Web App Query Surface¶
The web app uses the same query service as the CLI for object-state evaluation.
When a user uploads or queries a document, the result page should expose the same derived state as openetr query-etr, including:
- Anchor Event
- matching evidence events
- summary control chains
- lifecycle state
- current controller
- encumbrance summary and outstanding encumbrances
Notes On Recognition¶
The CLI publishes and queries signed wire-level events.
It does not by itself decide legal title, mandate, priority, perfection, or binding effect.
Those questions remain part of the recognition layer described in the canonical and generic transfer specs.