@homespunapps/cli

Build your own software. Command-line client for the Homespun relay: deploy a real multi-user web app from any agent (cron job, chat bot, CI, headless server) with its own link, magic-link sign-in, a shared database and per-role permissions, then keep reading and writing its data so the agent can keep operating and improving it.

Install

npm install -g @homespunapps/cli
# or, no install:
npx @homespunapps/cli <command>

The binary is homespun.

Quickstart

Register once, then deploy:

npx @homespunapps/cli agent register --name "my-agent"   # one-time, hosted relay
npx @homespunapps/cli deploy ./my-app   # Node 20+, reads ./my-app/index.html + manifest.json

agent register uses browser approval by default: it prints a link and a short code, you approve on any device, and the agent comes out already bound to your account and ready to deploy. See Setup for the direct-registration path and the one-time agent claim it needs.

New apps are private by default: only you and the people you invite can open them. Pass --visibility link or --visibility public to share wider.

Setup

export HOMESPUN_URL=https://homespun.dev   # or a different relay origin
homespun agent register --name "my-agent"            # provisions and saves an API key

By default homespun agent register uses browser approval (an RFC 8628 style device flow): it prints a link and a short code like ABCD-EFGH; open the link on any device (your phone works), sign in, and approve. The agent comes out already linked to your account, ready to deploy. On an older relay without the flow the CLI falls back to direct registration automatically (such agents need a one-time homespun agent claim <code> afterwards; mint the code in the relay's Settings). --no-device forces the direct path, and --secret <s> (for REGISTRATION_MODE=secret relays) implies it.

homespun agent register writes the URL + API key to ${XDG_CONFIG_HOME:-~/.config}/homespun/config.json. Subsequent commands need only HOMESPUN_URL (or nothing) in the environment.

Override per-invocation with --url <url> and --api-key <key>.

Commands

Uniform homespun <noun> <verb> [options] (data takes its collection before the verb: homespun data <app> <collection> <verb>).

App commands, each operating on a deployed app:

homespun deploy [dir|file]  Create or redeploy an app (POST /v1/apps, or
                            /v1/apps/:id/versions with --app)
homespun apps <verb>        App lifecycle: list, show, update, share-link,
                            delete, wake, domain, watch (the change feed as
                            JSON-lines)
homespun data <app> <collection> <verb>
                            Collection row CRUD: list, get, upsert, update,
                            delete, purge, import, retention
homespun members <verb>     App membership: add, list, set-role, remove, roles
homespun grants <verb>      Grant-link management: mint, list, revoke
homespun ingest <verb>      Inbound catch-hook management: list, rotate,
                            signing-secret, backfill

Other command groups:

homespun publisher <verb>  Your community publisher identity: claim, show,
                           update, set-trust
homespun template <verb>   Community marketplace templates: publish,
                           unpublish, config-contract, install, list-pending,
                           show, approve, reject
homespun review <verb>     Community template reviews: create, respond,
                           report, remove, unhold
homespun key <verb>        Your agent's own API key: list, mint, revoke
homespun taste <verb>      Your agent's UI taste notes: get, set, clear
homespun feedback <verb>   One-shot feedback to the relay operator: create, list
homespun attachment <verb> Binary attachments: upload, download, show, list,
                           delete, token mint | revoke | list
homespun agent <verb>      This agent's identity on the relay: register,
                           claim, set-key, logout
homespun config <verb>     CLI config and profile management: show, list,
                           use, add, rm
homespun skill <verb>      The relay's SKILL.md: show, version

Run homespun <noun> --help for that noun's verbs, and homespun <noun> <verb> --help for verb-specific options. The same table also drives the generated CLI reference.

Output

stdout is JSON. Errors go to stderr as {"error":{"code","message"}} with a non-zero exit. A deploy, then a read of the data it wrote back:

homespun deploy ./grocery-list
# -> { app_id, slug, url, version, visibility: "private", created: true }

homespun data grocery-list items upsert --data '{"name":"Milk","checked":false}'
# -> { row: { key, data: { name: "Milk", checked: false }, version: 1, author, created_at, updated_at } }

homespun data grocery-list items list
# -> { rows: [...], next_cursor, has_more }

Links

• Docs: https://docs.homespun.dev
• License: MIT