Reference

CLI

dropfast is the first-party command line for the whole v1 REST API: publish files/folders/stdin, list and search, versions and diffs, metadata, the comment review loop, aliases, sharing grants, teams, and server-side bulk operations. It's a thin client — errors are the API's {code, message, fix} verbatim, and every command has JSON output for agents.

The package

Published on npm as @dropfast/cli.


Package	`@dropfast/cli`
Command	`dropfast`
Runtime	Node ≥18, zero-config (defaults to `https://dropfast.dev`)
Dependencies	`clipanion` + `typanion` only — small install, no native build
License	MIT
Versioning	Independent of the DropFast app; the CLI cuts its own semver releases

It wraps the REST API 1:1 and holds no business logic, so anything the CLI does you can also do with plain HTTP — the CLI just handles multipart uploads, ZIP-at-root packaging, create-vs-update tracking, and URL verification for you.

Install

bash

npm install -g @dropfast/cli     # global — puts `dropfast` on your PATH
dropfast --version               # your installed version
dropfast --help

One-off, without installing:

bash

npx @dropfast/cli publish ./report.html --access private

Update to the latest release, or check what's installed:

bash

npm install -g @dropfast/cli@latest    # update
npm view @dropfast/cli version         # latest published
dropfast --version                     # your installed version

Working inside the DropFast repo without a global install? Run it via npm run dropfast -- (or node packages/cli/bin/dropfast.mjs) — same surface. The REST API and the hosted skill remain the zero-install paths.

Setup

bash

dropfast login     # hidden prompt → saves to ~/.dropfast/credentials (mode 600)
dropfast auth --show

Key resolution order: --api-key flag → $DROPFAST_API_KEY → ~/.dropfast/credentials. Base URL: --base-url → $DROPFAST_BASE_URL → https://dropfast.dev.

Publish

bash

dropfast publish ./report.html --access private --meta df.project=acme --meta df.type=report
dropfast publish ./site-dir --name "Q3 plan"          # zips the dir, index.html at the ZIP root
cat report.html | dropfast publish - --name "Report"  # stdin
dropfast publish ./report.html --og-image ./card.png  # custom social-share card (uploaded)

--og-image sets the social-share card: an https URL, a /site-path, a local image file (detected on disk and uploaded), or none to reset to the auto card.

publish tracks each path in ~/.dropfast/state.json: the first publish creates a site, re-running the same command uploads a new version at the same slug and URL (--new forces a fresh site). The returned URL is HEAD-verified before it's reported (401/403 from a private or password-gated site counts as live).

Find, inspect, change

bash

dropfast sites ls --filter df.project=acme --sort updated
dropfast sites ls --q "auth redesign"
dropfast sites get <slug>
dropfast sites set <slug> --access public
dropfast sites set <slug> --og-image ./card.png                   # upload a custom social card
dropfast sites set <slug> --og-image none                        # reset to the auto card
dropfast meta set <slug> --meta df.type=review --unset df.parent   # read-merge-write
dropfast versions ls <slug>
dropfast versions diff <slug> 1 2

Bulk operations

bulk set, bulk meta, and bulk rm call POST /api/v1/sites/bulk — one server-side batch, not a client loop. They are dry-run by default; --yes executes.

bash

dropfast bulk set --filter df.project=acme --access private        # preview: what would change
dropfast bulk set --filter df.project=acme --access private --yes  # execute
dropfast bulk meta --slugs a1,b2,c3 --set df.type=archived --yes
dropfast bulk rm --filter df.type=scratch --yes
dropfast bulk publish ./out/*.html --access private                # client-side fan-out, one site per file

A partially failed batch exits 5 and lists per-slug errors in results[].

Review loop

bash

dropfast comments ls <slug> --status open
dropfast comments add <slug> --body "Wrong total" --selector "#invoice .total"
dropfast comments resolve <comment-id>

For agents

dropfast llms prints the entire command tree as JSON — every command with its flags, one example, and its JSON output shape. One read = the whole surface. (CLI analog of /llms.txt and /api/openapi.json.)
--json is the default whenever stdout is not a TTY, so pipes and agent harnesses get machine-readable output without asking. Errors are {code, message, fix} JSON on stderr — the same vocabulary as the error taxonomy.
Deterministic exit codes:

Exit	Meaning
`0`	Success
`1`	API or other runtime error
`2`	Usage error (bad flags/arguments, refused confirmation)
`3`	Auth (`401`/`403`)
`4`	Not found (`404`)
`5`	Bulk operation partially failed (`summary.failed > 0`)

Destructive commands (sites rm, alias rm, bulk rm, …) require --yes when run non-interactively.

The full surface

plaintext

AUTH      login · auth --show | --clear
PUBLISH   publish <file|dir|-> · sites ls|get|update|set|rm
VERSIONS  versions ls|get|diff
METADATA  meta get|set
COMMENTS  comments ls|add|resolve|reopen
ALIASES   alias ls|create|repoint|rm
SHARING   share <slug> --email|--domain|--team · share ls|rm · shared
KEYS      keys ls|create|rm        (session-gated — manage keys on the dashboard)
TEAMS     teams ls|create|get|rm|transfer · teams members add|rm
BULK      bulk set|meta|rm (server-side) · bulk publish <files…>
AGENTS    llms

Every command answers --help with its flags, one example, and its output shape.

Edit this page on GitHub

PreviousREST API Next Access control