Hypercerts CLI

The Hypercerts CLI (hc) is a command-line tool for managing hypercerts on ATProto. You can use it to:

Create, read, update, and delete all Hypercerts record types (activities, measurements, evaluations, evidence, and more)
Authenticate with any ATProto PDS
Run interactively with a terminal UI or non-interactively with flags for CI/CD
Resolve identities and inspect any record on the network

Built in Go on bluesky-social/indigo with interactive forms powered by Charm libraries. Source: github.com/GainForest/hypercerts-cli.

Install

Choose one of three installation methods:

Quick install (recommended):

Terminal

curl -sSL https://raw.githubusercontent.com/GainForest/hypercerts-cli/main/install.sh | bash

Go install (requires Go 1.25+):

Terminal

go install github.com/GainForest/hypercerts-cli/cmd/hc@v0.1.1

Build from source:

Terminal

git clone https://github.com/GainForest/hypercerts-cli
cd hypercerts-cli
make build

Authenticate

Terminal

hc account login -u yourhandle.certified.app -p your-app-password

Check your session status:

Terminal

hc account status

Log out:

Terminal

hc account logout

For CI/CD, set HYPER_USERNAME, HYPER_PASSWORD, and optionally ATP_PDS_HOST as environment variables.

Core commands

All record types follow the same CRUD pattern. Here's the full workflow using activities as the primary example:

Terminal

# Create interactively (launches TUI form)
hc activity create


# Create with flags
hc activity create \
  --title "Rainforest Carbon Study" \
  --description "12-month carbon sequestration measurement" \
  --start-date 2025-01-01 \
  --end-date 2025-12-31


# List
hc activity ls
hc activity ls --json


# Get details
hc activity get <rkey>


# Edit
hc activity edit <rkey> --title "Updated Title"


# Delete (cascades to linked measurements and attachments)
hc activity delete <rkey> -f

Deleting an activity also removes all linked measurements and attachments. Use the -f flag to skip confirmation.

All record types

Every record type supports create, ls, get, edit, delete with the same flag patterns shown above.

Command	Record Type	Alias
`hc activity`	`org.hypercerts.claim.activity`	—
`hc measurement`	`org.hypercerts.claim.measurement`	`hc meas`
`hc location`	`app.certified.location`	`hc loc`
`hc attachment`	`org.hypercerts.claim.attachment`	`hc attach`
`hc rights`	`org.hypercerts.claim.rights`	—
`hc evaluation`	`org.hypercerts.claim.evaluation`	`hc eval`
`hc collection`	`org.hypercerts.claim.collection`	`hc coll`
`hc contributor`	`org.hypercerts.claim.contributorInformation`	`hc contrib`
`hc funding`	`org.hypercerts.funding.receipt`	`hc fund`
`hc workscope`	`org.hypercerts.helper.workScopeTag`	`hc ws`

Generic operations

Inspect any record on the network using AT-URIs:

Terminal

hc get at://did:plc:xxx/org.hypercerts.claim.activity/rkey

List all records for a user:

Terminal

hc ls handle.example.com

List records filtered by collection:

Terminal

hc ls handle.example.com --collection org.hypercerts.claim.activity

Resolve a handle to a DID:

Terminal

hc resolve handle.example.com

Interactive UI

When you run commands without flags, the CLI launches interactive forms with keyboard navigation, live preview cards during activity creation, multi-select for bulk deletes, and select-or-create patterns when linking records.

The interactive UI requires a terminal that supports ANSI escape codes. For CI/CD environments, always use flags to run commands non-interactively.