API

rf command line

Search, plan, install, publish and buy from the terminal with rf: install, configuration, exit codes, money rules and every command, generated from the real --help.

rf (also installed as reuseforge) is the command line for ReuseForge. Each command maps onto one or more API operations, so anything you can do here you can do from the SDKs or with curl. It is Node 18+ with no runtime dependencies (it embeds the JavaScript SDK). Output is human text on a terminal and JSON when piped or with --json; errors go to stderr.

Install

git clone https://github.com/Longfordjames/Claude-1 && cd Claude-1
npm install -g ./cli
rf --version                      # prints the version and where the SDK comes from
rf search rag --free              # no token needed to read

A Python port with the same flags, exit codes, files and lock semantics ships in the Python package (pip install ./sdk/python gives you a reuseforge and an rf command). It covers the day-to-day commands; the Node CLI documented here is the complete one.

Five minutes

rf login                                # opens the token page; paste the token (no echo). CI: echo "$TOKEN" | rf login --with-token
rf whoami                               # account, scopes and the remaining spend allowance
rf search rag --kind skill --free --limit 5
rf plan "RAG chatbot over my PDF invoices" --budget 50 --out plan.json
rf install acme/invoice-extractor       # verify, write, update reuseforge.lock
rf install --from-plan pln_abc123       # the hosted items of a plan option
rf list; rf verify                      # what is installed; re-hash it against the lock (offline)
rf init && rf publish --dry-run         # publish your own: see the publishing guide

Everything that changes something supports --dry-run, which prints the requests it would send and sends none. rf add and rf pull are aliases of install.

Configuration

Highest wins:

1. flags;
2. environment: REUSEFORGE_TOKEN, REUSEFORGE_API_URL, REUSEFORGE_PROFILE, REUSEFORGE_MAX_SPEND_CENTS, NO_COLOR, REUSEFORGE_CONFIG_DIR;
3. the project file ./.reuseforge/config.json (api_url, profile, target; never tokens), found by walking up to the git root;
4. the user config $XDG_CONFIG_HOME/reuseforge/config.json (default ~/.config/reuseforge/, %APPDATA%\reuseforge on Windows);
5. credentials.json next to it, mode 0600 (the CLI refuses to read it if group or world readable): {"profiles": {"default": {"api_url", "token", "account"}}};
6. the defaults: https://reuseforge.com/api/v1, anonymous.

rf config get|set|unset edits the config files. rf doctor checks reachability, the token and its scopes and clock skew (which matters for webhook signatures), and prints the effective configuration with the source of each value and no secrets. The SDKs read the same files and variables, so rf login once and your scripts are signed in too. To use your own node: rf --api-url http://127.0.0.1:8420/api/v1 whoami or REUSEFORGE_API_URL.

Exit codes

Scripts can branch on the exit code without parsing text.

With --json a failure prints the Problem JSON plus exit_code on stdout as well (stderr carries the human text), so a script never parses stderr:

rf items get acme/nothing --json | jq '{code, exit_code, request_id}'

Money rules

The CLI is stricter than the API about spending, because it is often run unattended.

1. Commands that commit money (orders pay, projects back, projects transfer, install --buy) print a summary first (items, total in dollars, fee, rail and a test-mode banner) and ask Proceed? [y/N] on a terminal.
2. --yes alone never pays. Without a terminal (or with --no-input) a spend needs --yes and a ceiling: --max-spend <usd> or REUSEFORGE_MAX_SPEND_CENTS, checked against the order total before any request is sent. This CLI also requires the ceiling with --yes on a terminal.
3. orders accept releases escrow to the seller and cannot be undone. It always asks on a terminal (type the order id again); without one it needs --yes --confirm <order_id>. It refuses to try unless rf whoami lists the orders:accept scope, which only a person can grant. rf mcp serve never forwards it.
4. rf install never pays. For a paid item it prints the server's order_hint and exits 7; --buy creates the order and applies rules 1 and 2.
5. The CLI keeps nothing that can spend money except the token, so put spend limits on the token: rf tokens create --scopes items:read,orders:pay --spend-limit 20. rf whoami shows what is left. See agent limits.

Install safety and the lockfile

rf install verifies every file sha256 and the bundle content_hash before anything is written (exit 10 on a mismatch, nothing touched); resolves paths inside the project root and refuses absolute paths, .. and symlink escapes; writes atomically; strips setuid, setgid and sticky bits; caps a version at 2 MiB and 100 files; and never executes anything from a package (suggested commands run only with --run-commands and a confirmation, and never when the descriptor says never). Config files such as .mcp.json are merged key by key; a conflicting key stops the install unless --force.

reuseforge.lock is written by install, lock, update and uninstall: one entry per resolved package with the exact version, the bundle content_hash, per-file hashes and targets, sorted so diffs stay small. rf install with a lock installs exactly the locked versions; rf install --frozen is for CI (never writes the lock, exit 5 if it cannot be satisfied); rf update re-resolves within the ranges in reuseforge.json; rf verify is offline and exits 10 if an installed file differs; rf uninstall removes only files that still match the lock.

Local MCP bridge, completion

rf mcp serve is a local stdio MCP server that proxies to the hosted tools with your credentials, for clients without remote MCP (see the MCP guide). --read-only forwards only read-only tools.

rf completion bash > ~/.local/share/bash-completion/completions/rf
rf completion zsh  > "${fpath[1]}/_rf"
rf completion fish > ~/.config/fish/completions/rf.fish

Commands

Everything below is generated from the output of rf --help and rf <command> --help of the CLI in this repository, so flags and wording are exactly what the program prints. Where a command is the CLI form of an operation, the operation's reference page shows an example with it in the CLI tab.

Global options

Global options work before or after the command. They are the same for every command.

Commands

rf login

rf login [options]

Store a personal access token for this machine (credentials file, mode 0600)

Without --with-token, opens the token page in your browser and asks you to paste the token (no echo). With --with-token the token is read from stdin: echo $TOKEN | rf login --with-token. The token is verified with GET /me before it is stored and is never printed.

Changes something, so --dry-run shows the request(s) without sending them.

rf logout

rf logout [options]

Remove the stored token for the profile (optionally revoke it on the server first)

Changes something, so --dry-run shows the request(s) without sending them.

rf tokens

Personal access tokens

rf tokens create

rf tokens create [options]

Create a token (read-only scopes by default). The secret is shown once.

Scopes: items:read, items:write, items:publish, orders:read, orders:create, orders:pay, orders:accept, projects:read, projects:write, webhooks:manage, tokens:manage, admin. orders:accept (release escrow) is refused unless --allow-accept. Tokens with orders:pay get a spend limit of $50.00 unless you set one with --spend-limit.

Changes something, so --dry-run shows the request(s) without sending them.

rf tokens list

rf tokens list [options]

List your tokens (never the secrets)

rf tokens revoke

rf tokens revoke <token_id>

Revoke a token by id (tok_...)

Changes something, so --dry-run shows the request(s) without sending them.

rf whoami

rf whoami

Show the signed-in account, token scopes and remaining spend allowance

rf items

Items: get, create, update, retract, star, stats

rf items create

rf items create <item> [options]

Create an item (metadata only; use rf publish to upload a version)

Changes something, so --dry-run shows the request(s) without sending them.

rf items descriptor

rf items descriptor <item> [options]

Show the install descriptor of an item for a target (what rf install would write)

rf items get

rf items get <item> [options]

Show one item

rf items retract

rf items retract <item>

Retract an item (hidden from search; existing buyers keep access)

Changes something, so --dry-run shows the request(s) without sending them.

rf items search

rf items search [query]... [options]

Search hosted items (alias of rf items search)

rf search rag --kind skill --free
rf search "invoice pdf" --max-price 20 --sort rating

rf items star

rf items star <item>

Star an item

Changes something, so --dry-run shows the request(s) without sending them.

rf items stats

rf items stats <item> [options]

Views, downloads, stars, reviews and sales of an item (daily series for owners)

rf items unstar

rf items unstar <item>

Remove your star from an item

Changes something, so --dry-run shows the request(s) without sending them.

rf items update

rf items update <item> [options]

Change item metadata (reads the ETag itself and sends If-Match)

Changes something, so --dry-run shows the request(s) without sending them.

rf reviews

Reviews: list, create, delete

rf reviews create

rf reviews create <item> [options]

Review an item you installed or bought (one per account; sending again replaces nothing, delete first)

Changes something, so --dry-run shows the request(s) without sending them.

rf reviews delete

rf reviews delete <item>

Delete your review of an item

Changes something, so --dry-run shows the request(s) without sending them.

rf reviews list

rf reviews list <item> [options]

List reviews of an item

rf search

rf search [query]... [options]

Search hosted items (alias of rf items search)

rf search rag --kind skill --free
rf search "invoice pdf" --max-price 20 --sort rating

rf versions

Versions: list, get, yank, download

rf versions download

rf versions download <item> [version] [options]

Download a version into a directory, verifying every hash first (does not install or lock)

Changes something, so --dry-run shows the request(s) without sending them.

rf versions get

rf versions get <item> [version]

Show one version: files, dependencies, verification

rf versions list

rf versions list <item> [options]

List published versions of an item

rf versions yank

rf versions yank <item> <version> [options]

Yank a version (stays downloadable for existing lockfiles, skipped by new resolution); --undo restores it

Changes something, so --dry-run shows the request(s) without sending them.

rf versions publish

rf versions publish [options]

Same as rf publish: publish the project as a new immutable version

Reads reuseforge.json, validates it, lists the files and the content hash, scans for secrets, creates the item when missing and uploads the version. It never changes the price of an existing item. The upload carries a deterministic Idempotency-Key, so repeating an interrupted publish cannot create a second version.

Changes something, so --dry-run shows the request(s) without sending them.

rf init

rf init [options]

Scaffold reuseforge.json from the current directory (detects SKILL.md, package.json, pyproject.toml, .mcp.json)

Changes something, so --dry-run shows the request(s) without sending them.

rf publish

rf publish [options]

Publish the project as a new immutable version (creates the item if it does not exist)

Reads reuseforge.json, validates it, lists the files and the content hash, scans for secrets, creates the item when missing and uploads the version. It never changes the price of an existing item. The upload carries a deterministic Idempotency-Key, so repeating an interrupted publish cannot create a second version.

Changes something, so --dry-run shows the request(s) without sending them.

rf install

rf install [item]... [options]

Install items and their dependencies (also: rf add, rf pull); with no arguments, install reuseforge.json / reuseforge.lock

Every file hash and the bundle content_hash are verified before anything is written; paths are confined to the project; writes are atomic; nothing from a package is executed. A paid item you do not own stops with exit 7 and prints the order to create (use --buy to buy it as part of the run).

Changes something, so --dry-run shows the request(s) without sending them.

rf install acme/invoice-extractor
rf install acme/pdf-text-layer@^2 --target claude-code
rf install --frozen
rf install --from-plan pln_abc123 --buy --yes --max-spend 20

rf list

rf list [options]

List what reuseforge.lock says is installed

rf lock

rf lock [item]... [options]

Resolve reuseforge.json dependencies (and named items) and write reuseforge.lock without installing files

Changes something, so --dry-run shows the request(s) without sending them.

rf uninstall

rf uninstall <package> [options]

Remove an installed item: only files recorded in the lock whose hash still matches are deleted; edited files are left and reported

Changes something, so --dry-run shows the request(s) without sending them.

rf update

rf update [package] [options]

Re-resolve installed items within their ranges to the highest non-yanked version and install the changes

Changes something, so --dry-run shows the request(s) without sending them.

rf verify

rf verify [options]

Re-hash every installed file against reuseforge.lock, offline; exit 10 on drift

Subcommands rf verify request <item> [version] and rf verify get <id> handle attested test runs on the server.

rf verify get

rf verify get <verification_id>

Show a verification (vrf_...)

rf verify request

rf verify request <item> [version] [options]

Ask the platform to run the version's tests in its sandbox and attest the result

Changes something, so --dry-run shows the request(s) without sending them.

rf connectors

Discovery connectors

rf connectors list

rf connectors list [options]

List discovery connectors and whether they are ready

rf discover

rf discover <query>... [options]

Search external sources (GitHub, npm, PyPI, crates, arXiv, HF, MCP registries) without planning

rf mcp-config

rf mcp-config [options]

MCP servers that fit a plan or goal; --write merges them into .mcp.json (asks first)

Changes something, so --dry-run shows the request(s) without sending them.

rf plan

rf plan <goal>... [options]

Turn a goal and a budget into a Pareto-optimal plan: reuse, buy or build

Prints the recommended option, the Pareto table (quality up, cost down, risk down) and the reasoning. Nothing is bought. A plan is stored for 24 hours; its id is a capability.

Changes something, so --dry-run shows the request(s) without sending them.

rf plan "RAG chatbot over my PDF invoices" --budget 50
rf plan "scrape and summarize arXiv papers" --online --exclude-paid --out plan.json

rf plans

Stored plans: get, brief

rf plans brief

rf plans brief <plan_id> [options]

Build brief for the parts of a plan option that must be built (markdown for an agent or a person)

rf plans get

rf plans get <plan_id>

Show a stored plan

rf admin

Operator actions

rf admin resolve

rf admin resolve <order_id> <item_id> [options]

Operator: resolve a disputed order item by splitting the escrow (basis points to the seller)

Changes something, so --dry-run shows the request(s) without sending them.

rf orders

Orders and escrow: create, pay, accept, dispute, ...

rf orders accept

rf orders accept <order_id> [options]

Accept delivery and RELEASE the escrow to the seller (irreversible; needs the orders:accept scope)

Always asks on a terminal (type the order id). Without a terminal it needs --yes --confirm <order_id>. The CLI refuses to try when rf whoami does not list orders:accept: that scope can only be granted by a person in the web app and must never be handed to an autonomous agent.

Changes something, so --dry-run shows the request(s) without sending them.

rf orders cancel

rf orders cancel <order_id>

Cancel an unpaid order

Changes something, so --dry-run shows the request(s) without sending them.

rf orders create

rf orders create [options]

Create an order from a plan or from items. Nothing is paid until rf orders pay.

Changes something, so --dry-run shows the request(s) without sending them.

rf orders create --plan pln_abc123
rf orders create --item acme/invoice-extractor@1.4.0 --rail simulated

rf orders deliver

rf orders deliver <order_id> [options]

Seller: mark items as delivered (buyer access starts here; the buyer has the accept window to review)

Changes something, so --dry-run shows the request(s) without sending them.

rf orders dispute

rf orders dispute <order_id> [options]

Open a dispute: freezes the release of the disputed items until an operator decides

Changes something, so --dry-run shows the request(s) without sending them.

rf orders get

rf orders get <order_id>

Show an order: items, escrow state, payment instructions, next steps

rf orders list

rf orders list [options]

List your orders (as buyer, or --role seller)

rf orders pay

rf orders pay <order_id> [options]

Pay an order into escrow (asks first; non-interactive runs need --yes and --max-spend)

Prints the items, total, fee, rail and destination, then asks "Proceed? [y/N]". Without a terminal it refuses (exit 11) unless --yes is given AND the total is within --max-spend / REUSEFORGE_MAX_SPEND_CENTS: --yes alone never pays. The token's own spend limit applies on top. On real rails send the funds first and pass the transaction with --tx.

Changes something, so --dry-run shows the request(s) without sending them.

rf orders refund

rf orders refund <order_id> <item_id> [options]

Seller: refund one item of an order to the buyer (irreversible)

Changes something, so --dry-run shows the request(s) without sending them.

rf payouts

Seller payouts and earnings

rf payouts earnings

rf payouts earnings

Escrowed, releasable, available and paid-out amounts

rf payouts list

rf payouts list [options]

Your payouts as a seller

rf portfolio

rf portfolio [options]

Your project backings: invested, dividends and ownership

rf projects

Crowdfunded projects

rf projects abort

rf projects abort <project_id> [options]

Vote to abort a project and refund the remaining funds (--undo withdraws the vote)

Changes something, so --dry-run shows the request(s) without sending them.

rf projects attach

rf projects attach <project_id> [options]

Attach the hosted item that is the finished product of a project

Changes something, so --dry-run shows the request(s) without sending them.

rf projects back

rf projects back <project_id> [options]

Pledge money to a project (spending rules apply: asks first; no terminal needs --yes and --max-spend)

Changes something, so --dry-run shows the request(s) without sending them.

rf projects create

rf projects create [options]

Propose a crowdfunded build project

Changes something, so --dry-run shows the request(s) without sending them.

rf projects deliver

rf projects deliver <project_id> <index> [options]

Developer: submit evidence that a milestone is done

Changes something, so --dry-run shows the request(s) without sending them.

rf projects finalize

rf projects finalize <project_id> <index>

Close voting on a milestone once the outcome is decided

Changes something, so --dry-run shows the request(s) without sending them.

rf projects get

rf projects get <project_id>

Show a project: milestones, developers, cap table

rf projects list

rf projects list [options]

Crowdfunded build projects

rf projects transfer

rf projects transfer <project_id> [options]

Transfer revenue units of a project to another account (asks first)

Changes something, so --dry-run shows the request(s) without sending them.

rf projects vote

rf projects vote <project_id> <index> [options]

Backer: approve or reject a submitted milestone (weighted by pledge)

Changes something, so --dry-run shows the request(s) without sending them.

rf projects withdraw

rf projects withdraw <project_id> <backing_id>

Withdraw a pledge that is not yet confirmed

Changes something, so --dry-run shows the request(s) without sending them.

rf events

Webhook event types

rf events types

rf events types

Webhook event types

rf webhooks

Webhook endpoints and deliveries

rf webhooks create

rf webhooks create [options]

Create an endpoint. The signing secret (whsec_...) is printed once.

Changes something, so --dry-run shows the request(s) without sending them.

rf webhooks delete

rf webhooks delete <webhook_id>

Delete an endpoint (pending deliveries are dropped)

Changes something, so --dry-run shows the request(s) without sending them.

rf webhooks deliveries

rf webhooks deliveries <webhook_id> [options]

Delivery log of an endpoint

rf webhooks get

rf webhooks get <webhook_id>

Show one endpoint

rf webhooks list

rf webhooks list [options]

List webhook endpoints

rf webhooks redeliver

rf webhooks redeliver <webhook_id> <delivery_id>

Send an earlier event again (same event id; receivers must de-duplicate)

Changes something, so --dry-run shows the request(s) without sending them.

rf webhooks rotate-secret

rf webhooks rotate-secret <webhook_id>

Rotate the signing secret; the old one keeps verifying for a grace period. The new secret is printed once.

Changes something, so --dry-run shows the request(s) without sending them.

rf webhooks test

rf webhooks test <webhook_id>

Send a ping event to an endpoint and show the delivery attempt

Changes something, so --dry-run shows the request(s) without sending them.

rf webhooks update

rf webhooks update <webhook_id> [options]

Change URL, events, description or enable/disable an endpoint

Changes something, so --dry-run shows the request(s) without sending them.

rf accounts

Public account profiles

rf accounts get

rf accounts get <handle>

Public profile of a user or organization

rf api

API meta: index, health, openapi, rate-limit

rf api health

rf api health

Liveness and dependency check (exit 9 when the API reports itself down)

rf api index

rf api index

The API entry point: version, links, payment rails, limits, deprecations

rf api openapi

rf api openapi [options]

Fetch the OpenAPI contract this deployment serves

rf api rate-limit

rf api rate-limit

Your current rate-limit windows per tier

rf completion

rf completion <shell>

Print a shell completion script (bash, zsh or fish)

Install, for example: rf completion bash > ~/.local/share/bash-completion/completions/rf

rf config

Read and write rf configuration (api_url, profile, target)

rf config get

rf config get [key]

Show the effective value (and where it comes from) of api_url, profile or target

rf config set

rf config set <key> <value> [options]

Set api_url, profile or target in the user config (or the project config with --project)

Config files never hold tokens. Environment variables and flags still override these values; see rf config get.

Changes something, so --dry-run shows the request(s) without sending them.

rf config unset

rf config unset <key> [options]

Remove a key from the user config (or the project config with --project)

Changes something, so --dry-run shows the request(s) without sending them.

rf doctor

rf doctor

Check configuration, credentials, connectivity, token scopes and clock skew

Prints the effective configuration without secrets. Exit 0 when nothing failed (warnings are fine); otherwise the exit code of the first failure (3 credentials, 9 network).

rf ledger

Ledger events of self-hosted nodes

rf ledger pull

rf ledger pull [options]

Read signed ledger events (JSON, or JSONL with --out)

rf ledger push

rf ledger push [file]

Submit signed events (from a file or stdin) to the API; invalid ones are reported, never blocking the rest

The file holds a JSON array, {"events": [...]}, or one event per line. "-" or no file reads stdin. Batches of 500 events / 2.5 MiB, each with a deterministic idempotency key so a repeat is harmless. Needs the items:write scope.

Changes something, so --dry-run shows the request(s) without sending them.

rf ledger sync

rf ledger sync <node_url> [options]

Two-way sync with a self-hosted node: pull its new events into the API, then pull the API's new events into the node

The node is any server that speaks /ledger/events. Its token comes from REUSEFORGE_NODE_TOKEN (never from your ReuseForge token, which is not sent to other servers). Cursors are remembered per node in the user config directory so the next run only moves new events.

Changes something, so --dry-run shows the request(s) without sending them.

rf marketplaces

The hosted Claude Code marketplace of an account (its public, free, active items)

rf marketplaces get

rf marketplaces get <owner>

The hosted Claude Code marketplace of an account (its public, free, active items)

rf mcp

Hosted MCP server: mcp serve is a stdio proxy

rf mcp serve

rf mcp serve [options]

Run a local stdio MCP server that proxies to the hosted ReuseForge tools with your credentials

For MCP clients without remote-MCP support: command "rf", args ["mcp", "serve"]. Stdout carries only protocol messages; diagnostics go to stderr. accept_order is never forwarded (releasing escrow needs a human: rf orders accept). The token is used as stored; to limit what an agent can spend, give it a token with --spend-limit.

Last updated: 2026-11-03