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.
--actor-type, --actor-name, and --client-source are global flags: they're accepted on every subcommand (including comment add, thread resolve, branding, and so on), not only the ones listed below. The flag tables document them under publish and share to keep the per-command pages readable; the meaning is the same wherever you pass them.
publish
$ dsp publish [path]Publish an HTML or Markdown file. Use a single dash for stdin (requires --id).
| Flag | Value | Description |
|---|---|---|
--name <name> | string | Display name override. Optional — defaults to the filename without the extension on first publish. On update (with --id), renames the artifact (the slug re-derives) as part of the republish. |
--id <shortId> | string | Update an existing artifact (bumps to the next version). |
--base-version <n> | positive integer | Required with --id. Pass the current artifact version you edited from. |
--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). |
--reload | boolean | Refresh anyone currently viewing the artifact as soon as the publish lands. Off by default — the default behaviour is a polite "Refresh to vN" affordance on the version pill that the reader can dismiss. Use --reload for author-iteration cadence in a single open tab; omit it when sharing with an audience so a comment composer mid-flight isn't yanked away. Open composers defer the reload until they're blurred and empty. |
--actor-type <type> | human | agent | Override the auto-detected actor classification. The CLI infers human when a stdio handle is a TTY, agent otherwise; flip it when a human is piping output or a custom script wants to declare agent identity. Equivalent env var: DISPLAYDEV_ACTOR_TYPE. See Actor for what each value means. |
--actor-name <name> | ASCII string ≤128 chars | Display name stamped on the artifact's version history alongside the actor classification (e.g. [email protected], ci-deploy-bot, manual-cleanup-batch-3). Equivalent env var: DISPLAYDEV_ACTOR_NAME. |
--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.
When updating an artifact, fetch the current baseline first with dsp get <shortId>, export the source with dsp export <shortId> if you need the current bytes, then publish with --base-version <currentVersion>. If the artifact changed since you started editing, the CLI prints the server's current version so you can reconcile and retry.
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. |
--actor-type <type> | human | agent | Override auto-detected actor classification (see publish). |
--actor-name <name> | ASCII string ≤128 chars | Display name stamped on the audit log (see publish). |
--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.
Set DISPLAYDEV_ACTOR_TYPE (human or agent) and DISPLAYDEV_ACTOR_NAME to declare actor identity once across the session, equivalent to passing --actor-type and --actor-name on every invocation. The CLI infers --actor-type from whether a stdio handle is a TTY; override when a human is piping output or a script wants to declare an agent.
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.