@opencollectiblesfoundry/cli

ocf, the command-line tool for the OCF Core API.

Installation

npm install -g @opencollectiblesfoundry/cli

Usage

Configuration

ocf login     # Authenticate via the device authorization flow
ocf config env dev/prod  # Set the API environment
ocf --help

ocf config env dev/prod switches between environments. Auth tokens, projects and all their associated resources are scoped to the environments. The DEV environment has much more lax request rate and minted collectible limits.

ocf login prints a link to be opened in a browser to either login or create a new account. Once authorization is completed, the resulting access token is stored at ~/.ocf/session.json.

User

ocf user me                   # Show the currently authenticated user
ocf user resolve               # Resolve your email identity tokens internally
ocf user tokens list           # List tokens issued to the authenticated user

ocf user me fetches the profile of the currently authenticated user.

ocf user resolve links any pending email identity tokens to the account. It claims any tokens that were issued to the account email.

ocf user tokens list lists all tokens issued to the authenticated user across all projects.

Projects

ocf project list    # List projects and inspect one
ocf project create  # Create a new project
ocf project import  # Import an existing project by ID

Projects are created with ocf project create. The created project details and secrets are saved to ~/.ocf/session.json. Prefer the SDK for doing production scripts, or at least import the project from a safe info storage at runtime.

An pre-existing project can be added to the local session by providing its ID and the two secrets that were issued at creation time:

Project ID:      <uuid>
Client secret:   <hidden>
Project secret:  <hidden>

The project's name and slug are retrieved from the API, and the full entry (including both secrets) is saved to ~/.ocf/session.json under the active environment.

Schemas

ocf project schemas list          # List schemas
ocf project schemas get [id]      # Get a schema
ocf project schemas create        # Create a schema
ocf project schemas update [id]   # Update a schema
ocf project schemas delete [id]   # Delete a schema

All schemas are public and available to be used by other projects. The schema list can be filtered by a creator field. Schemas names and descriptions can be edited after creation, but the actual definition is inmmutable. Deletion is only possible when the schema is not used by a collectible or token.

Collectibles

ocf project collectibles list          # List collectibles
ocf project collectibles get [id]      # Get a collectible
ocf project collectibles create        # Create a collectible
ocf project collectibles update [id]   # Update a collectible
ocf project collectibles delete [id]   # Delete a collectible

Only local image files are supported when creating a collectible and a size limit may be applied. As with schemas, deletion is only possible when no associated token is recorded.

ocf project collectibles list keeps the interactive filter flow by default. Optional filters can also be supplied as flags to skip those prompts:

ocf project collectibles list --client-user-id "[email protected]" --created-at-from "2026-09-10"
ocf project collectibles list --external-ids "card-1,card-2" --metadata-filter rarity=rare

Tokens

ocf project tokens list                  # List issued tokens
ocf project tokens count                 # Count issued tokens
ocf project tokens get [id]              # Get a token
ocf project tokens create                # Issue a single token
ocf project tokens update [id]           # Update token metadata or privacy
ocf project tokens batch                 # Issue tokens for multiple collectibles and collectors
ocf project tokens batch-to-collector    # Issue multiple collectibles to one collector
ocf project tokens delete [id]           # Delete a token

List

Filter and sort fields are prompted for by default. Optional filters can also be supplied as flags to skip those prompts:

ocf project tokens list --client-user-id "[email protected]" --issued-at-from "2026-09-10"
ocf project tokens list --collectible-ids "collectible-id-1,collectible-id-2" --metadata-filter rarity=rare
ocf project tokens count --is-private false --token-schema-id "schema-id"

Results are displayed in an interactive paginator with 20 tokens per page. Optional prompts can be left blank to be omitted.

When a client user ID is provided, a stored project is selected and resolved to an account link before tokens are listed.

Collectible IDs are accepted as comma-separated values:

collectible-id-1, collectible-id-2

Metadata filters are added through the interactive metadata editor.

Create

A single token is issued. The collector identityToken is derived from the email and the selected project's secret before the API is called.

Required fields can be supplied as flags. Missing required fields are still prompted for, while omitted optional fields are skipped when any create flag is provided:

ocf project tokens create --collectible-id "collectible-id" --client-user-id "user-1" --email "[email protected]"
ocf project tokens create --collectible-id "collectible-id" --client-user-id "user-1" --email "[email protected]" --metadata rarity=rare --is-private false

Update

Token details are updated by ID. If no ID is provided, a token can be selected or an ID entered manually. Metadata patch entries are merged into the existing metadata. A value of null removes that metadata key. All metadata can be removed by choosing Clear metadata.

Batch Issue

Every selected collectible is issued to every collector. Collectible IDs are entered as a comma-separated list:

Collectible IDs:

collectible-id-1, collectible-id-2

Collectors:

clientUserId: user-1
email: [email protected]
metadata: tier=gold

Each collector identityToken is derived from email and the selected project's secret before the API is called.

Batch Issue To Collector

Multiple collectibles are issued to a single collector. This is used when each collectible of the tokens that will be issued will carry the same metadata.

Collector details are prompted for separately:

{ "clientUserId": "user-1", "email": "[email protected]" }

Collectibles are added one at a time. Per-collectible token metadata is added through the interactive metadata editor.

Collectible:

id: collectible-id-1
metadata: tier=gold

The collector identityToken is derived from email and the selected project's secret before the API is called.

Account Links

ocf project account-links list          # List account links
ocf project account-links get [id]      # Get an account link
ocf project account-links update [id]   # Update an account link
ocf project account-links delete [id]   # Delete an account link

Account links are static records that track the accounts tokens are issued too, even when their clientUserId is renamed.

Account links keep track of their associated total token count and when filtered by collectibleIds return a collectibles token count.