Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🛠️nexus tool

Audience: Nexus CLI users and integrators.

Command: nexus tool.

Generated from: Nexus CLI v2.1.1 release executable at commit 08bfe76e726922ce512d623fbc1d2e1bd786bcd4 (generated inventory preserved below).

This page is the complete help tree for nexus tool. Global output flags can appear after the family or nested subcommand.

Tool economy contract

The nexus tool cashier tree inspects accepted policies and the completed Invocation/deposit inbox, opens or closes finite-credit and time-pass issuance, buys or issues entitlements, and collects policy-homogeneous finalized Invocations or generic deposits. New Tool registration already accepts FixedPrice; change its price through top-level nexus tool set-invocation-cost rather than a cashier configuration command. Cashier owner mutations require CloneableOwnerCap<OverToolCashier>; registry endorsement requires ToolRegistryAdminCap; Tool lifecycle and result-verifier configuration use CloneableOwnerCap<OverTool>. The registration-time MetaSchema is immutable, so an incompatible FQN/module/schema/output/witness contract requires a new Tool identity. Callers select accepted policies and supply their exact entitlement object when required. See Invocation policy and settlement model.

Verify the selected binary’s nexus tool cashier --help, generated bindings, cashier capability, package IDs, and transaction effects before executing a command against a deployment.

Historical c8ff compatibility

The historical c8ff CLI/SDK exposed cashier expiry and cashier limited-invocations; those commands are absent from the documented CLI. Use those names only when maintaining an explicitly pinned historical client, and never substitute them for Invocation identity, receipts, entitlement/refund state, or policy-revenue collection.

nexus tool

Manage Nexus Tools

Usage: nexus tool [OPTIONS] <COMMAND>

Commands:
  new                  Create a new tool scaffolding with the specified name and template.
  validate             Validate a tool based on its type.
  register             Register a tool based on its type.
  cashier              Manage Tool economic policies and entitlements
  unregister           Unregister a Tool from live protocol lookup
  update-url           Update the HTTP endpoint of an offchain Tool
  update-metadata      Update the description of a Tool
  migrate-package      Update the package of an onchain Tool
  update-timeout       Update the execution timeout of a Tool
  set-invocation-cost  Set the invocation price of a Tool
  configure-verifier   Configure Tool response verification
  claim-collateral     Claim collateral for a tool identified by its FQN.
  list                 List all registered tools.
  inspect              Inspect a registered tool by FQN. Returns the derived Tool and ToolCashier
                       IDs and the complete semantic tool record when it exists.
  auth                 Manage tool auth for signed HTTP.
  help                 Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Output:
      --json        Emit machine readable JSON
  -v, --verbose...  Increase diagnostic detail
  -q, --quiet...    Show errors only

nexus tool new

For --template move, Standard mode has the UIDRequirements, OnchainToolResult prefix. Use --mode workflow-authorization to prepend ProvenValue<AgentVertexAuthorization> and implement its verification before mutation. --mode is rejected with --template rust. Move scaffolds use MVR dependencies, version = "1.0.0", and edition = "2024.alpha", without an [addresses] table.

nexus tool validate

nexus tool validate offchain

nexus tool validate onchain

This validator fetches a registered on-chain Tool by FQN, resolves its live execute and Output schemas, normalizes them into MetaSchema, and compares both the registered schema and Standard versus WorkflowAuthorization mode. Success reports the Tool state, or {"valid":true,"fqn":...,"tool":...} with --json.

It does not prove package lineage, UpgradeCap custody, dependency linkage, witness ownership, or business invariants. Use the on-chain Tool candidate-verification checklist when those proofs are required.

nexus tool register

nexus tool register offchain

nexus tool register onchain

nexus tool cashier

Manage one Tool's accepted Invocation policies and completed accounting inbox.

Merged commands include:

  • inspect — show accepted policies, configured terms, and canonical Tool economy.

  • inbox — list completed Invocations and prepaid deposits waiting for collection.

  • collect-invocations — collect one policy-homogeneous batch under the ToolCashier owner capability.

  • collect-deposits — collect one batch of prepaid sale deposits under owner authority.

  • access — inspect the configured beneficiary's access state.

  • finite-credits enable|close-issuance|open-issuance|update-terms|buy|issue|restore-refund — manage finite-credit entitlements and restore one refunded Invocation.

  • time-pass enable|close-issuance|open-issuance|update-terms|buy|issue — manage immutable time-pass entitlements.

The collection commands take an exact Tool FQN and one or more repeated exact Invocation or deposit IDs; owner capability and recipient flags are selected by the command's help:

The finite-credit recovery command is nexus tool cashier finite-credits restore-refund --tool-fqn <FQN> --invocation-id <OBJECT_ID>.

Owner configuration and collection require the ToolCashier administration capability CloneableOwnerCap<OverToolCashier>; registry endorsement is a separate ToolRegistryAdminCap operation. collect-invocations accepts one or more repeated exact Invocation IDs in one policy-homogeneous batch; collect-deposits accepts one or more repeated exact CashierDeposit IDs, which carry no policy field and therefore do not share that constraint. Closing issuance stops new buy/issue operations but preserves existing Credits and TimePass objects; update-terms applies to future objects. A caller may buy or use an accepted entitlement without those owner capabilities, but its beneficiary must match the Invocation payment source. Every authorization and refund remains tied to the exact Invocation identity.

Finite-credit buy requires open issuance, uses the configured minimum_credits/maximum_credits, and charges price_per_credit × credits; owner issue requires open issuance and the same bounds but does not charge the offer price. One canonical shared Credits account is derived from the ToolCashier and beneficiary, and its mutable remaining balance serializes authorization. There is no split, join, or refund-manager API. Any matching active Execution may attempt a shared Credits or frozen TimePass authorization, and source, remaining-unit, and validity checks can deny or require retry.

For TimePass, buy is bounded by the accepted price_per_ms, minimum_duration_ms, and maximum_duration_ms, while owner issue requires open issuance and only checks valid_from_ms < valid_until_ms; both returned passes are frozen by the SDK builders, whereas raw Move callers must freeze them themselves. Existing Credits and TimePass objects retain their Tool/Cashier identity and beneficiary or interval across URL/package changes and same-object re-registration, but Invocation admission still checks matching Tool/Cashier IDs, accepted policy, and payment source; registry endorsement and RegisteredKey/External result-verifier setup are separate operational/verification steps that may need renewal after registration state changes.

See Invocation policy and settlement model for policy terms, receipts, timeout refund, and collection invariants.

nexus tool unregister

nexus tool configure-verifier

nexus tool configure-verifier registered-key

nexus tool configure-verifier external

nexus tool claim-collateral

nexus tool set-invocation-cost

nexus tool list

nexus tool inspect

nexus tool auth

nexus tool auth keygen

nexus tool auth register-key

nexus tool auth list-keys

nexus tool auth export-allowed-leaders

nexus tool auth sync-allowed-leaders

nexus tool update-url

Update HTTP endpoint for an offchain Tool.

nexus tool update-metadata

Update the description for a Tool.

nexus tool migrate-package

Update the package for an onchain Tool.

nexus tool update-timeout

Last updated