@pepitahq/cli

Snapshot. Factored out of the private pepita monorepo, built and released from there, and not standalone-buildable. PRs are applied in the monorepo. https://pepita.dev

@pepitahq/cli

Command-line access to your pepita sites. Talks to app.pepita.dev over HTTPS; you sign in once via a browser-based device authorization — the way wrangler or gh do it, no pasted API key.

Install

npm i -g @pepitahq/cli    # then: pepita <command>
# or one-off:
npx @pepitahq/cli <command>

Use

pepita login                          # opens the browser to authorize this device
pepita list                           # your sites
pepita pull my-site --dir ./my-site   # download the working copy to a folder
# …edit files locally with your own tools…
pepita apply my-site --dir ./my-site  # upload local changes into the working copy
pepita preview my-site                # a shareable link to review first
pepita publish my-site                # put the current site live

Commands

Command	What it does
login	Authorize this device in the browser
logout	Remove the local token (revokes the device server-side)
whoami	Show the logged-in account — checked against the server, so a device whose access was revoked says so instead of reporting the cached email
list	List your sites
create <name> [--allow-embedding] [--block-ai-crawlers] [--from <dir>]	Create a new site (optionally seeded from a local folder). Embedding starts denied and AI visibility on — both changeable later in Settings → Advanced
pull <slug> [--live] [--preview <name>] [--dir <path>]	Download files (default: the working copy)
apply <slug> [--dir <path>] [--yes]	Upload local files into the site's working copy
preview <slug> [--update <name>] [--delete <name>]	Create, update, or remove a shareable preview link
previews <slug>	List active preview links
publish <slug>	Put the current site live
status [slug]	Without a slug: your balance + every site's URL. With one: that site's pending changes
delete <slug> [--download-snapshot] [--yes]	Permanently delete a site (optionally snapshot to /tmp first)
asset <sub> --site <slug>	Video assets: add <file> (upload + transcode), list, info <id>, rename <id> <new name> (label only — URLs keep working), rm <id>, pull <id> (download the original)
template <sub> --site <slug>	Confirmation-email templates, one per form: list, read <form-name> [--out body.html], put <form-name> [--file body.html] [--subject s] [--from local] [--from-name name] [--save] (upsert by form name — envelope-only puts re-send the current body; a put writes the WORKING COPY, --save does both in one step), save <form-name> (makes the working copy the version people receive), rm <form-name> [--yes], and the template's images: image add <form-name> <file>, image list <form-name> (name, size and the public URL of each), image rm <form-name> <image-name>
form <sub> --site <slug>	Form submissions: list (every collection + its count), get <form-name> [--live] [--preview <name>] [--csv <path>] [--xlsx <path>] [--json <path>] (without --live/--preview you get the editor's own test submissions). get prints EVERY record of that source — a form holds at most 1000 entries, so there is no cap and no refusal. --csv/--xlsx/--json write a file through the same server export the editor's download button uses, so the file the CLI writes and the one a founder downloads can't diverge; if a collection is too large even for that, the export is partial and the CLI says so rather than reporting success. A form whose entries carry more than 50 different field names can't be shown as a table at all — the error message tells you to download the raw JSON, which --json does (the one format immune to the column-merge refusal, since it has no columns to merge).

Videos never live in the site's file tree — apply refuses video files and points you at asset add, which uploads to the asset library and transcodes for streaming. A video already on the site and unchanged locally is skipped silently, so a pull → apply round-trip keeps working.

Video uploads cost money: hosting is metered at $0.60 per minute of source footage (per-second pro-rata), charged from your pepita balance when you upload — pepita status shows what's left. Only mp4, mov and m4v files are accepted, and by content, not by extension: a WebM renamed .mp4 is rejected before any upload starts.

If the server has moved past this CLI's version, every command prints one line on stderr telling you to update. It is a notice, never a block — nothing stops working because of it.

Templates live outside the site's file tree and are matched to a form by name (the form's _form value). The confirmation email's recipient is always the submission's email field — there is no --to-field flag, on this command or anywhere else.

A template can hold up to 10 images (JPEG or PNG, 300 kB each, 1 MB per template). Reference one in the email body by its bare filename — <img src="hero.jpg"> — and pepita turns it into a full URL when it sends; image list prints that URL if you need it elsewhere. Names are lowercased and tidied for you (Logo.PNG → logo.png), and the format is checked by content, not extension. Two things to know: uploading an image is immediate, but the <img> that references it is part of the template body, so it only reaches recipients after template save — and image rm is immediate too, so deleting one the saved body still names breaks that picture in the next email that goes out. Re-using a name is refused rather than overwritten: image URLs are cached for a long time, so the old picture could keep showing. Upload under a new name and point the template at it.

What pull downloads

target	what you get
(default)	the working copy — the site as it stands in the editor
--live	the published live site
--preview <name>	a specific preview link's files (name from previews)

apply uploads local files into the working copy; from there publish puts it live, and preview shares it at a stable link.

• The token is stored in ~/.pepita/config.json (mode 600). Revoke any device under your avatar → Settings → Devices. PEPITA_API_BASE overrides the host.

Notes

• pull writes/overwrites files locally but does NOT delete local files that are absent from the fetched state.
• apply will DELETE files from the working copy that exist remotely but not in your local directory — it shows a plan and asks for confirmation unless --yes is passed. Run apply from a complete copy of the site (ideally a fresh pull) to avoid surprise deletions.

Security

• The server stores only sha256(token); the raw token lives only on your machine.
• One-time PKCE code, 120 s TTL, loopback-only redirect.