The dsp binary ships with the @displaydev/cli npm package. Every subcommand below is the canonical surface. Run dsp <command> --help for the live list of flags on your installed version.
publish
$ dsp publish [path]Publish an HTML or Markdown file. Use a single dash for stdin (requires --id).
| Flag | Value | Description |
|---|---|---|
--name <name> | string | Artifact display name. Required on first publish. Optional on update — when supplied with --id, the artifact is renamed (slug re-derives) as part of the republish. |
--id <shortId> | string | Update an existing artifact (bumps to the next version). |
--public | boolean | Make the artifact publicly accessible (alias for --visibility public). |
--company | boolean | Restrict the artifact to your organization (alias for --visibility company). Default for authenticated publishes. |
--visibility <level> | public | company | private | Visibility level. private requires the Pro plan. |
--share <email> | repeatable string | Add an email to sharedWith. May be passed multiple times. |
--share-with <emails> | comma-separated string | Same as repeated --share, in one flag. |
--clear-shares | boolean | Remove every entry from sharedWith (update only). |
--theme <theme> | string (default github) | Markdown theme. Ignored for HTML publishes. |
--show-branding <mode> | show | hide | inherit | Override the Display.dev branding bar (paid plans only). |
--client-source <name> | string | Distribution-channel tag sent on the request for funnel analytics. Wrappers and skills set this automatically; you rarely set it yourself. Equivalent env var: DISPLAYDEV_CLIENT_SOURCE. |
If dsp runs without a saved credential or DISPLAYDEV_API_KEY, publish switches to the anonymous path and returns a preview URL plus a one-shot claim URL — see Publish without an account.
share
$ dsp share [shortId]Change an artifact's visibility and add or remove sharedWith emails.
| Flag | Value | Description |
|---|---|---|
--visibility <level> | public | company | private | New visibility level. |
--add-users <emails> | comma-separated string | Append these emails to sharedWith. |
--remove-users <emails> | comma-separated string | Remove these emails from sharedWith. |
--client-source <name> | string | Distribution-channel tag (see publish). |
At least one of --visibility / --add-users / --remove-users must be provided.
rename
$ dsp rename [shortId]Rename a published artifact. The slug re-derives from the new name; old URLs still resolve via shortId.
| Flag | Value | Description |
|---|---|---|
--name <name> (required) | string | New display name. |
find
$ dsp find [query]List or search artifacts in your organization. Omit [query] to list every artifact (paginated). Also available as `dsp list`.
| Flag | Value | Description |
|---|---|---|
--author <a> | repeatable string | Filter by author. Each value: email, userId, or me. Multiple values are ORed. me requires a user-scoped credential — passing it under an org API key is rejected. |
--visibility <list> | comma-separated public | company | private | Filter by visibility. private is creator-scoped — only your own private artifacts appear. |
--since <date> | ISO date-time | Only artifacts updated on or after this point. |
--sort <col> | updated_at | view_count | name | Sort column. Defaults to updated_at. |
--dir <direction> | asc | desc | Sort direction. Defaults: desc for updated_at / view_count, asc for name. |
--cursor <token> | opaque string | Pagination token from a prior response. Drop the cursor when filters change — re-using it after a different --author / --visibility / --since / [query] silently skews results. |
--limit <n> | integer 1–100 | Max rows to return. Defaults to 50. |
Output is one row per line on stdout (shortId vN name url). When the response carries more pages, a footer on stderr reports the visible-vs-total count and the next-page cursor — pipe consumers (dsp find | xargs …) get clean stdout.
get
$ dsp get [shortId]Print artifact details (metadata + version list) as JSON.
| Flag | Value | Description |
|---|---|---|
--include <field> | repeatable string (e.g. versions) | Include extra fields beyond the default metadata. |
export
$ dsp export [shortId]Print the published source bytes to stdout. Pin a version by appending @ and a number, e.g. dsp export abc123@2.
| Flag | Value | Description |
|---|---|---|
--format <format> | original | markdown (default original) | original returns the bytes as uploaded. markdown converts an HTML artifact to Markdown via Workers AI. |
delete
$ dsp delete [shortId]Delete an artifact permanently. Pass --confirm to skip the safety prompt.
| Flag | Value | Description |
|---|---|---|
--confirm | boolean | Skip the safety prompt. Required to actually delete. |
login
$ dsp loginAuthenticate with display.dev — OTP, SSO device flow, or API key.
| Flag | Value | Description |
|---|---|---|
--email <email> | string | Email address. Required for the OTP / SSO branches in non-interactive runs; not used with --api-key. |
--code <code> | 6-digit string | OTP code (verify step). Pair with --email. |
--api-key [key] | string (optional value) | Authenticate with an API key. Without a value, prompts (TTY) or reads stdin (non-TTY). |
--json | boolean | Machine-readable structured output instead of prose. |
--client-source <name> | string | Distribution-channel tag (see publish). |
branding
$ dsp branding [shortId] [mode]Override Display.dev branding for an existing artifact (show, hide, inherit) without re-publishing. Hiding requires a paid plan.
No additional flags.
mcp
$ dsp mcpStart the MCP server over stdin/stdout. Your AI assistant spawns this — you don't run it yourself. See MCP server for host configuration.
No additional flags. The server's behaviour depends on whether the CLI has a saved credential — see MCP server.
Authentication
The CLI reads (in order):
DISPLAYDEV_API_KEY— environment variable. Highest precedence.~/.displaydev/config.json— written bydsp login.
Set DISPLAYDEV_API_URL when targeting local dev (e.g. http://api.display.test:3331); otherwise the CLI defaults to production.
Set DISPLAYDEV_CLIENT_SOURCE if you're embedding dsp in a wrapper that should report a distribution channel — equivalent to passing --client-source <name> on every invocation.
Exit codes
0— success.1— generic failure (auth invalid, server error, network issue).2— usage error (missing required flag, malformed argument).4— artifact not found or no permission.