> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# cowboy store

> Find, hire, publish and manage actors in the General Store

`cowboy store` is the General Store from the command line. Hirers search, review a listing's plan, and hire; creators declare an actor, publish versions and submit them for review. Many subcommands use the protocol's own names, defined in [CIP-33](https://docs.cowboy.inc/cips/cip-33-actor-hiring-and-distribution.md).

```bash theme={"system"}
cowboy store search moderator
cowboy store hire <listing> --plan
```

To hire step by step, see [Hire from the CLI](https://docs.cowboy.inc/hire/hire-from-the-cli.md). To sell, see [List an actor](https://docs.cowboy.inc/sell/list-an-actor.md).

```text theme={"system"}
cowboy store [OPTIONS] <COMMAND>
```

| Command | Description |
| - | - |
| [`declaration-id`](#cowboy-store-declaration-id) | Calculate the deterministic declaration id for creator, actor, and salt |
| [`declare`](#cowboy-store-declare) | Declare a hireable actor and its first artifact/version |
| [`list`](#cowboy-store-list) | List connections configured for this environment |
| [`version`](#cowboy-store-version) | Declare a new version/artifact for an existing declaration |
| [`current`](#cowboy-store-current) | Show the effective Store selection without contacting a node |
| [`retire`](#cowboy-store-retire) | Retire a declaration |
| [`add`](#cowboy-store-add) | Save a verified Store connection for this environment |
| [`register-store`](#cowboy-store-register-store) | Register a distribution store |
| [`grant`](#cowboy-store-grant) | Grant a store distribution rights for a declaration |
| [`remove`](#cowboy-store-remove) | Remove a local connection and reset its saved selection |
| [`revoke-grant`](#cowboy-store-revoke-grant) | Revoke a distribution grant |
| [`use`](#cowboy-store-use) | Select a Store within the current environment |
| [`register-artifact`](#cowboy-store-register-artifact) | Register a store artifact for an existing declaration version |
| [`search`](#cowboy-store-search) | Search or browse the complete public catalog |
| [`retire-artifact`](#cowboy-store-retire-artifact) | Retire an artifact |
| [`show`](#cowboy-store-show) | Inspect a public listing's capabilities, pricing and setup availability |
| [`hires`](#cowboy-store-hires) | Read authenticated hire history for the selected Store and wallet |
| [`deposit`](#cowboy-store-deposit) | Deposit more funds into a hire |
| [`submit`](#cowboy-store-submit) | Submit a prepared public package for review, without publishing it |
| [`submissions`](#cowboy-store-submissions) | Read recent intake records and optionally match an original prepared input |
| [`withdraw`](#cowboy-store-withdraw) | Withdraw unused prepaid funds |
| [`renew`](#cowboy-store-renew) | Renew a hire |
| [`set-renewal`](#cowboy-store-set-renewal) | Enable or disable hire auto-renewal |
| [`hire`](#cowboy-store-hire) | Hire an offering and set it up locally, or select explicit protocol or recovery inputs |
| [`pause`](#cowboy-store-pause) | Pause a hire |
| [`revoke`](#cowboy-store-revoke) | Revoke a hire |
| [`status`](#cowboy-store-status) | Inspect an installation, or inspect local setup with `--hire-id` |
| [`settle`](#cowboy-store-settle) | Settle a per-call hire with a hirer-signed receipt, or a provider-metered hire with `--provider-metered` as the listing's creator. |
| [`sign-per-call-receipt`](#cowboy-store-sign-per-call-receipt) | Sign a per-call receipt as the hirer and print it as hex |
| [`unpause`](#cowboy-store-unpause) | Unpause an existing hire |
| [`attest`](#cowboy-store-attest) | Attest a manifest root |
| [`get-*`](#read-store-records) | Read Store records |

Every `cowboy store` command takes these options:

| Option | Description |
| - | - |
| `--store <SELECTED>` | |
| `--json` | |

## cowboy store declaration-id

Calculate the deterministic declaration id for creator, actor, and salt

```text theme={"system"}
cowboy store declaration-id [OPTIONS] --creator <CREATOR> --actor <ACTOR> --salt <SALT>
```

| Option | Description |
| - | - |
| `--creator <CREATOR>` | Creator address that will sign the declaration |
| `--actor <ACTOR>` | Actor address being declared hireable |
| `--salt <SALT>` | 32-byte declaration salt, hex encoded |

## cowboy store declare

Declare a hireable actor and its first artifact/version

```text theme={"system"}
cowboy store declare [OPTIONS] --actor <ACTOR> --salt <SALT> --manifest-root <MANIFEST_ROOT> --code-visibility <CODE_VISIBILITY> --volume-id <VOLUME_ID> --claimed-root <CLAIMED_ROOT>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--actor <ACTOR>` | Actor address being declared hireable |
| `--salt <SALT>` | 32-byte declaration salt, hex encoded |
| `--human-hireable` | Mark the actor human-hireable |
| `--agent-hireable` | Mark the actor agent-hireable |
| `--manifest-root <MANIFEST_ROOT>` | 32-byte manifest root, hex encoded |
| `--code-visibility <CODE_VISIBILITY>` | Code visibility: public or private |
| `--capability-schema-hex <CAPABILITY_SCHEMA_HEX>` | Capability schema bytes, hex encoded |
| `--capability-schema-file <CAPABILITY_SCHEMA_FILE>` | Capability schema bytes from a file |
| `--term <TERMS>` | Pricing term spec. Repeatable: free, one-shot:cby:1.5, subscription:cby:10:1000, per-call:cby:call=0.01,result=0.001, provider-metered:cby:event=0.001, or CIP-20 variants one-shot:cip20:\<token\_id>:\<base\_units> |
| `--split <SPLIT>` | Split spec `<address>:<bps>`. Required; repeatable; shares sum to 10000 |
| `--volume-id <VOLUME_ID>` | CBFS volume id holding the artifact |
| `--claimed-root <CLAIMED_ROOT>` | Claimed artifact root; must match manifest-root on declare/version |
| `--ibe-ciphertext-hex <IBE_CIPHERTEXT_HEX>` | Escrow IBE ciphertext, hex encoded. Required for `--code-visibility` private; omit for public (the chain rejects a non-empty escrow on public code) |
| `--ibe-ciphertext-file <IBE_CIPHERTEXT_FILE>` | Escrow IBE ciphertext bytes from a file. Required for `--code-visibility` private; omit for public |

## cowboy store list

List connections configured for this environment

```text theme={"system"}
cowboy store list [OPTIONS]
```

## cowboy store version

Declare a new version/artifact for an existing declaration

```text theme={"system"}
cowboy store version [OPTIONS] --declaration-id <DECLARATION_ID> --manifest-root <MANIFEST_ROOT> --code-visibility <CODE_VISIBILITY> --volume-id <VOLUME_ID> --claimed-root <CLAIMED_ROOT>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--declaration-id <DECLARATION_ID>` | |
| `--manifest-root <MANIFEST_ROOT>` | |
| `--code-visibility <CODE_VISIBILITY>` | |
| `--capability-schema-hex <CAPABILITY_SCHEMA_HEX>` | |
| `--capability-schema-file <CAPABILITY_SCHEMA_FILE>` | |
| `--term <TERMS>` | |
| `--split <SPLIT>` | |
| `--volume-id <VOLUME_ID>` | |
| `--claimed-root <CLAIMED_ROOT>` | |
| `--ibe-ciphertext-hex <IBE_CIPHERTEXT_HEX>` | |
| `--ibe-ciphertext-file <IBE_CIPHERTEXT_FILE>` | |

## cowboy store current

Show the effective Store selection without contacting a node

```text theme={"system"}
cowboy store current [OPTIONS]
```

## cowboy store retire

Retire a declaration

```text theme={"system"}
cowboy store retire [OPTIONS] --declaration-id <DECLARATION_ID>
```

| Option | Description |
| - | - |
| `--declaration-id <DECLARATION_ID>` | |

## cowboy store add

Save a verified Store connection for this environment

```text theme={"system"}
cowboy store add [OPTIONS] --url <URL> <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | |

| Option | Description |
| - | - |
| `--url <URL>` | |

## cowboy store register-store

Register a distribution store

```text theme={"system"}
cowboy store register-store [OPTIONS]
```

| Option | Description |
| - | - |
| `--metadata <METADATA>` | Store metadata bytes as UTF-8 text |
| `--metadata-hex <METADATA_HEX>` | Store metadata bytes as hex |
| `--metadata-file <METADATA_FILE>` | Store metadata bytes from a file |
| `--prepare` | Sign and print the transaction without submitting it |

## cowboy store grant

Grant a store distribution rights for a declaration

```text theme={"system"}
cowboy store grant [OPTIONS] --declaration-id <DECLARATION_ID> --lease-epoch-blocks <LEASE_EPOCH_BLOCKS>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--declaration-id <DECLARATION_ID>` | |
| `--store-id <STORE_ID>` | |
| `--split <SPLIT>` | |
| `--max-referral-bps <MAX_REFERRAL_BPS>` | Default: `0`. |
| `--lease-epoch-blocks <LEASE_EPOCH_BLOCKS>` | |

## cowboy store remove

Remove a local connection and reset its saved selection

```text theme={"system"}
cowboy store remove [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | |

## cowboy store revoke-grant

Revoke a distribution grant

```text theme={"system"}
cowboy store revoke-grant [OPTIONS] --grant-id <GRANT_ID>
```

| Option | Description |
| - | - |
| `--grant-id <GRANT_ID>` | |

## cowboy store use

Select a Store within the current environment

```text theme={"system"}
cowboy store use [OPTIONS] <NAME>
```

| Argument | Description |
| - | - |
| `<NAME>` | |

## cowboy store register-artifact

Register a store artifact for an existing declaration version

```text theme={"system"}
cowboy store register-artifact [OPTIONS] --declaration-id <DECLARATION_ID> --version <VERSION> --volume-id <VOLUME_ID> --claimed-root <CLAIMED_ROOT>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--store-id <STORE_ID>` | |
| `--declaration-id <DECLARATION_ID>` | |
| `--version <VERSION>` | |
| `--volume-id <VOLUME_ID>` | |
| `--claimed-root <CLAIMED_ROOT>` | |
| `--ibe-ciphertext-hex <IBE_CIPHERTEXT_HEX>` | |
| `--ibe-ciphertext-file <IBE_CIPHERTEXT_FILE>` | |

## cowboy store search

Search or browse the complete public catalog

```text theme={"system"}
cowboy store search [OPTIONS] [QUERY]
```

| Argument | Description |
| - | - |
| `[QUERY]` | |

| Option | Description |
| - | - |
| `--limit <LIMIT>` | Default: `2000`. |
| `--offset <OFFSET>` | Default: `0`. |

## cowboy store retire-artifact

Retire an artifact

```text theme={"system"}
cowboy store retire-artifact [OPTIONS] --declaration-id <DECLARATION_ID> --version <VERSION> --artifact-id <ARTIFACT_ID>
```

| Option | Description |
| - | - |
| `--declaration-id <DECLARATION_ID>` | |
| `--version <VERSION>` | |
| `--artifact-id <ARTIFACT_ID>` | |

## cowboy store show

Inspect a public listing's capabilities, pricing and setup availability.

No wallet or login is required. For installation inputs, secrets, permissions and funding requirements, use cowboy store hire LISTING `--plan`.

```text theme={"system"}
cowboy store show [OPTIONS] <LISTING>
```

| Argument | Description |
| - | - |
| `<LISTING>` | |

## cowboy store hires

Read authenticated hire history for the selected Store and wallet

```text theme={"system"}
cowboy store hires [OPTIONS]
```

| Option | Description |
| - | - |
| `--declaration <DECLARATION>` | |
| `--version <VERSION>` | |

## cowboy store deposit

Deposit more funds into a hire

```text theme={"system"}
cowboy store deposit [OPTIONS] --hire-id <HIRE_ID> --amount <AMOUNT>
```

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |
| `--asset <ASSET>` | Default: `cby`. |
| `--amount <AMOUNT>` | |
| `--token-id <TOKEN_ID>` | |

## cowboy store submit

Submit a prepared public package for review, without publishing it

```text theme={"system"}
cowboy store submit [OPTIONS] --input <FILE>
```

| Option | Description |
| - | - |
| `--input <FILE>` | |

## cowboy store submissions

Read recent intake records and optionally match an original prepared input

```text theme={"system"}
cowboy store submissions [OPTIONS]
```

| Option | Description |
| - | - |
| `--match-input <FILE>` | |

## cowboy store withdraw

Withdraw unused prepaid funds

```text theme={"system"}
cowboy store withdraw [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |

## cowboy store renew

Renew a hire

```text theme={"system"}
cowboy store renew [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--hire-id <HIRE_ID>` | |

## cowboy store set-renewal

Enable or disable hire auto-renewal

```text theme={"system"}
cowboy store set-renewal [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |
| `--on` | Enable renewal |
| `--off` | Disable renewal |

## cowboy store hire

Hire an offering and set it up locally, or select explicit protocol or recovery inputs

```text theme={"system"}
cowboy store hire [OPTIONS] [LISTING]
```

| Argument | Description |
| - | - |
| `[LISTING]` | |

| Option | Description |
| - | - |
| `--declaration-id <DECLARATION_ID>` | |
| `--version <VERSION>` | |
| `--grant-id <GRANT_ID>` | |
| `--term <TERM>` | Pricing term spec chosen from the declaration terms |
| `--referral <REFERRAL>` | Optional referral `<address>:<bps>` |
| `--asset <ASSET>` | Payment asset: cby or cip20 |
| `--amount <AMOUNT>` | Payment amount. CBY accepts up to 9 decimals; CIP-20 is raw base units |
| `--token-id <TOKEN_ID>` | Required for `--asset cip20`; 32-byte token id |
| `--max-fee <MAX_FEE>` | Cap the acquisition's declared native fee |
| `--max-payment <MAX_PAYMENT>` | |
| `--max-payment-asset <ASSET>` | |
| `--yes` | |
| `--resume <RESUME>` | Recover only the existing acquisition transaction |
| `--new-hire` | |
| `--no-setup` | Buy the entitlement without running setup |
| `--plan` | Review requirements without signing transactions or creating journals |
| `--inputs <FILE>` | |
| `--secret <NAME=@PATH>` | |
| `--funding-tx <STEP=HASH>` | |
| `--max-setup-fee <MAX_SETUP_FEE>` | Cap cumulative native setup fees separately from acquisition |
| `--recipe-hash <RECIPE_HASH>` | |
| `--hire-id <HIRE_ID>` | Continue local setup for an existing hire without buying again |
| `--installation-id <INSTALLATION_ID>` | Continue an existing hosted installation |
| `--hosted` | Deliberately create a new account-backed hosted installation |
| `--request-id <REQUEST_ID>` | |
| `--retry` | |
| `--max-spend <MAX_SPEND>` | Approve the hosted installation's total principal and fee ceiling |
| `--receipt-timeout <RECEIPT_TIMEOUT>` | |
| `--declaration <DECLARATION>` | |

Forms:

```text theme={"system"}
LISTING              Acquire and run reviewed local setup.
--no-setup           Acquire without setup.
--resume             Recover only an acquisition transaction.
--hire-id            Continue local setup without buying.
--hosted             Create a hosted installation using a Labs account.
--installation-id    Continue a hosted installation.
--declaration-id     Submit a protocol hire with --term and --amount.
```

## cowboy store pause

Pause a hire

```text theme={"system"}
cowboy store pause [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--hire-id <HIRE_ID>` | |

## cowboy store revoke

Revoke a hire

```text theme={"system"}
cowboy store revoke [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--hire-id <HIRE_ID>` | |

## cowboy store status

Inspect an installation, or inspect local setup with `--hire-id`.

Hosted status reads the Labs journal without a private key. Completed runs attempt handoff verification using the public Store review and selected RPC within one total five-second budget. Journal output remains available when verification fails. Available guidance does not establish actor runtime health or app reachability.

```text theme={"system"}
cowboy store status [OPTIONS] [INSTALLATION_ID]
```

| Argument | Description |
| - | - |
| `[INSTALLATION_ID]` | |

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |
| `--declaration <DECLARATION>` | |
| `--version <VERSION>` | |

Forms:

```text theme={"system"}
--hire-id            Inspect local setup using wallet-authenticated history.
INSTALLATION_ID      Inspect a hosted installation using its Labs account.
```

## cowboy store settle

Settle a per-call hire with a hirer-signed receipt, or a provider-metered hire with `--provider-metered` as the listing's creator. Waits for the committed result and fails if the chain rejects the settlement

```text theme={"system"}
cowboy store settle [OPTIONS] --hire-id <HIRE_ID> --counts <COUNTS>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--hire-id <HIRE_ID>` | |
| `--session-receipt-hex <SESSION_RECEIPT_HEX>` | |
| `--session-receipt-file <SESSION_RECEIPT_FILE>` | |
| `--provider-metered` | Settle a provider-metered hire: send no receipt, signed by the declaration's creator, which reports the counts |
| `--counts <COUNTS>` | Cumulative count of each unit of the hire's term, in the term's order, comma-separated (e.g. `3,40` for 3 calls and 40 results). For a per-call hire they must be the counts the receipt was signed for |

## cowboy store sign-per-call-receipt

Sign a per-call receipt as the hirer and print it as hex.

The receipt authorizes the hire's pinned split to draw `--cumulative` base units in total for per-call usage. Anyone can submit it with `trading-post settle`.

```text theme={"system"}
cowboy store sign-per-call-receipt [OPTIONS] --hire-id <HIRE_ID> --version <VERSION> --actor <ACTOR> --cumulative <CUMULATIVE> --counts <COUNTS> --nonce <NONCE> --expires-at <EXPIRES_AT>
```

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |
| `--version <VERSION>` | The hire's pinned declaration version |
| `--actor <ACTOR>` | The serving actor (the declaration's actor) |
| `--cumulative <CUMULATIVE>` | Total owed for per-call usage, in base units: the sum of each unit's count times its price |
| `--counts <COUNTS>` | Cumulative count of each unit of the hire's term, in the term's order, comma-separated (e.g. `3,40`). The receipt commits to them |
| `--nonce <NONCE>` | Must be greater than the nonce of the last settled receipt |
| `--expires-at <EXPIRES_AT>` | Last block at which the receipt settles |
| `--chain-identity <CHAIN_IDENTITY>` | Closed chain identity JSON; discover once from RPC when omitted |

## cowboy store unpause

Unpause an existing hire

```text theme={"system"}
cowboy store unpause [OPTIONS] --hire-id <HIRE_ID>
```

| Option | Description |
| - | - |
| `--hire-id <HIRE_ID>` | |
| `--prepare` | |

## cowboy store attest

Attest a manifest root

```text theme={"system"}
cowboy store attest [OPTIONS] --manifest-root <MANIFEST_ROOT> --verdict <VERDICT>
```

| Option | Description |
| - | - |
| `--prepare` | Sign and print the transaction without submitting it |
| `--manifest-root <MANIFEST_ROOT>` | |
| `--verdict <VERDICT>` | approved, rejected, or flagged |
| `--policy-uri <POLICY_URI>` | Policy URI bytes as UTF-8 text |
| `--policy-uri-hex <POLICY_URI_HEX>` | Policy URI bytes as hex |
| `--policy-uri-file <POLICY_URI_FILE>` | Policy URI bytes from a file |

## Read Store records

| Command | Description |
| - | - |
| `cowboy store get-declaration [OPTIONS] --declaration-id <DECLARATION_ID>` | Get a declaration by id |
| `cowboy store get-version [OPTIONS] --declaration-id <DECLARATION_ID> --version <VERSION>` | Get a declaration version |
| `cowboy store get-store [OPTIONS]` | Get a store by id |
| `cowboy store get-store-artifacts [OPTIONS]` | List artifacts for a store |
| `cowboy store get-grant [OPTIONS] --declaration-id <DECLARATION_ID>` | Get a grant by store and declaration |
| `cowboy store get-hire [OPTIONS] --hire-id <HIRE_ID>` | Get a hire by id |
| `cowboy store get-per-call-channel [OPTIONS] --hire-id <HIRE_ID>` | Get the settlement state of a PerCall or ProviderMetered hire's channel |
| `cowboy store get-hirer-hires [OPTIONS] --hirer <HIRER>` | List hires for a hirer address |
| `cowboy store get-attestations [OPTIONS] --manifest-root <MANIFEST_ROOT>` | List attestations for a manifest root |
| `cowboy store get-lease-authorize [OPTIONS] --runner <RUNNER> --job <JOB> --hire <HIRE>` | Check runner lease authorization for a hire-bound job |

Each command's `--help` lists its optional flags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.