--- title: CLI reference description: Every subcommand of the @displaydev/cli package, with flag tables. slug: /docs/cli-reference group: publishing updatedAt: 2026-06-19 --- The `dsp` binary ships with the `@displaydev/cli` npm package. Every subcommand below is the canonical surface. Run `dsp --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 ```bash $ dsp publish [path] ``` Publish an HTML or Markdown file. Use a single dash for stdin (requires --id). | Flag | Value | Description | | ------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--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 ` | string | Update an existing artifact (bumps to the next version). | | `--base-version ` | 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 ` | `public` \| `company` \| `private` | Visibility level. `private` requires the Pro plan. | | `--share ` | repeatable string | Add an email to `sharedWith`. May be passed multiple times. | | `--share-with ` | comma-separated string | Same as repeated `--share`, in one flag. | | `--clear-shares` | boolean | Remove every entry from `sharedWith` (update only). | | `--theme ` | string (default `github`) | Markdown theme. Ignored for HTML publishes. | | `--show-branding ` | `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 ` | `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](/docs/concepts#actor) for what each value means. | | `--actor-name ` | ASCII string ≤128 chars | Display name stamped on the artifact's version history alongside the actor classification (e.g. `claude-code@1.0.45`, `ci-deploy-bot`, `manual-cleanup-batch-3`). Equivalent env var: `DISPLAYDEV_ACTOR_NAME`. | | `--client-source ` | 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](/docs/claimable). When updating an artifact, fetch the current baseline first with `dsp get `, export the source with `dsp export ` if you need the current bytes, then publish with `--base-version `. If the artifact changed since you started editing, the CLI prints the server's current version so you can reconcile and retry. ## share ```bash $ dsp share [shortId] ``` Change an artifact's visibility and add or remove sharedWith emails. | Flag | Value | Description | | ------------------------- | ---------------------------------- | ------------------------------------------------------------ | | `--visibility ` | `public` \| `company` \| `private` | New visibility level. | | `--add-users ` | comma-separated string | Append these emails to `sharedWith`. | | `--remove-users ` | comma-separated string | Remove these emails from `sharedWith`. | | `--actor-type ` | `human` \| `agent` | Override auto-detected actor classification (see `publish`). | | `--actor-name ` | ASCII string ≤128 chars | Display name stamped on the audit log (see `publish`). | | `--client-source ` | string | Distribution-channel tag (see `publish`). | At least one of `--visibility` / `--add-users` / `--remove-users` must be provided. ## rename ```bash $ 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 ` (required) | string | New display name. | ## find ```bash $ 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 ` | 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 ` | comma-separated `public` \| `company` \| `private` | Filter by visibility. `private` is creator-scoped — only your own private artifacts appear. | | `--since ` | ISO date-time | Only artifacts updated on or after this point. | | `--sort ` | `updated_at` \| `view_count` \| `name` | Sort column. Defaults to `updated_at`. | | `--dir ` | `asc` \| `desc` | Sort direction. Defaults: `desc` for `updated_at` / `view_count`, `asc` for `name`. | | `--cursor ` | 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 ` | 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 ```bash $ dsp get [shortId] ``` Print artifact details (metadata + version list) as JSON. | Flag | Value | Description | | ------------------- | ----------------------------------- | ------------------------------------------------- | | `--include ` | repeatable string (e.g. `versions`) | Include extra fields beyond the default metadata. | ## export ```bash $ 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 ` | `original` \| `markdown` (default `original`) | `original` returns the bytes as uploaded. `markdown` converts an HTML artifact to Markdown via Workers AI. | ## delete ```bash $ 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 ```bash $ dsp login ``` Authenticate with display.dev — OTP, SSO device flow, or API key. | Flag | Value | Description | | ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ | | `--email ` | string | Email address. Required for the OTP / SSO branches in non-interactive runs; not used with `--api-key`. | | `--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 ` | string | Distribution-channel tag (see `publish`). | ## branding ```bash $ 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 ```bash $ dsp mcp ``` Start 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](/docs/mcp-server). ## Authentication The CLI reads (in order): - `DISPLAYDEV_API_KEY` — environment variable. Highest precedence. - `~/.displaydev/config.json` — written by `dsp 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 ` 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.