@hypersocial/decks-cli

Command-line client for Hypersocial Decks live analytics and share management.

Most users should install the friendlier package name:

pnpm dlx hyperdecks whoami

This package targets production by default:

pnpm dlx @hypersocial/decks-cli login
pnpm dlx @hypersocial/decks-cli whoami
pnpm dlx @hypersocial/decks-cli deck list
pnpm dlx @hypersocial/decks-cli deck stats netflix
pnpm dlx @hypersocial/decks-cli activity --limit 20
pnpm dlx @hypersocial/decks-cli import ./claude-design-export.zip --slug acme-pitch
pnpm dlx @hypersocial/decks-cli skills install

Global install:

pnpm add -g @hypersocial/decks-cli
decks login
decks activity

Auth

decks login opens the production broker at https://decks.hypersocial.ai and stores a refresh credential in:

~/.config/hypersocial-decks/credentials.json

Headless usage:

decks login --token <refresh-or-pat>
HSDECKS_TOKEN=<refresh-or-pat> decks whoami

Commands

login [--token <pat>] [--broker <url>]
logout
whoami [--json]

deck list [--json]
deck stats <slug> [--json]
deck open <slug>

share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]
share list <slug> [--json]
share on|off <token>
share rm <token>
share url <token>

recipient archive|unarchive <name>
import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live|archived]
skills install [--agent codex,claude-code] [--all-agents]
activity [--deck <slug>] [--limit <n>] [--json]

Development Target

Production is the default because this CLI is for real recipient activity and customer-facing share management.

Use dev only for local implementation/testing:

decks --dev --convex https://your-dev.convex.cloud --broker https://decks.localhost whoami
HSDECKS_PROD=0 HSDECKS_CONVEX_URL=https://your-dev.convex.cloud HSDECKS_BROKER_BASE=https://decks.localhost decks whoami

Legacy unauthenticated dev access is available with --admin or HSDECKS_ADMIN=1. It is rejected for production.

Claude Design Imports

Export a Claude Design project as standalone HTML or a ZIP, then import it into Hyperdecks:

# From a local export…
decks import ./claude-design-export.zip --slug acme-pitch --title "Acme Pitch"
# …or directly from a downloadable export URL (no local file needed):
decks import https://example.com/claude-design-export.zip --slug acme-pitch
decks share new acme-pitch "Jane at Acme" --email [email protected]

The import command uploads bundled assets, rewrites local asset references, and stores large generated HTML in Convex file storage so it can be sent through per-recipient share links with analytics.

The URL form must point at the downloadable export bytes (a ZIP or standalone HTML). A claude.ai/design/p/... project page is not importable on its own — use the project's Export/Download to get a direct URL or a local ZIP. Only http(s) is allowed and loopback/private hosts are refused.

MCP

The same import is exposed to agents via the hypersocial-decks MCP server as the import_deck_from_url tool:

// import_deck_from_url
{ "url": "https://example.com/claude-design-export.zip", "slug": "acme-pitch", "status": "draft" }

It authenticates with the stored CLI credential — run decks login --prod first.