Use the dsp CLI to publish, update, inspect, share, and delete artifacts from a terminal or script. This page covers the core artifact workflow. Run dsp --help to see every command in your installed version, including comments, threads, members, email domains, organization logos, and watch settings.
--actor-type and --actor-name are global flags for regular CLI commands. The tables document them under publish and share to keep this page readable. The dsp mcp server is the exception: it gets agent identity from the connected MCP client instead of these flags or their environment variables.
First publish from the command line
If you want your AI tool to handle setup, start with Quickstart. To publish files yourself from a terminal, install the CLI and sign in:
npm install -g @displaydev/cli
dsp loginComplete the sign-in instructions, then publish an HTML or Markdown file from your computer:
dsp publish <file> --name "Project update" --visibility privateReplace <file> with your file's path. The CLI prints the artifact's URL. Open it in your browser and sign in if asked. Private means only you can open it until you invite someone or change its visibility. See Sharing and access for sharing options.
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 and re-derives the slug. |
--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). Organization-scoped service keys use this default. |
--visibility <level> | public | company | private | Visibility level. User-scoped publishes default to private; organization-scoped service publishes default to company. Private is available on every plan. |
--share <email> | repeatable string | Invite a person by email. May be passed multiple times. |
--share-with <emails> | comma-separated string | Same as repeated --share, in one flag. |
--clear-shares | boolean | Remove every invited email address (update only). |
--theme <theme> | string (default github) | Markdown theme. Ignored for HTML publishes. |
--reload | boolean | Refresh open viewer tabs when the new version is ready. Off by default – viewers instead get a Refresh to vN action they can dismiss. An open comment form delays automatic refresh until it is no longer active and is 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. claude-code@1.0.45, ci-deploy-bot, manual-cleanup-batch-3). Equivalent env var: DISPLAYDEV_ACTOR_NAME. |
If dsp runs without a saved credential or DISPLAYDEV_API_KEY, publish returns a preview URL plus a single-use claim URL – see Publish without an account.
When updating an artifact, fetch the current baseline with dsp get-metadata <shortId>. Use dsp search <query> --in <shortId> and dsp read <shortId> to inspect the source, then use dsp edit for one exact replacement. Use dsp export when you need the complete local file and dsp publish --id when you need to replace the complete source.
An update must keep the format established for the artifact. Use a .md file for a
Markdown artifact and a .html file for an HTML artifact. Publish a new
artifact when converting between Markdown and HTML.
make-copy
$ dsp make-copy [shortId][@version]Make an independent copy of an artifact from one retained version.
| Flag | Value | Description |
|---|---|---|
--name <name> | string | Name for the new artifact. Defaults to Copy of <source name>. |
--visibility <level> | public | company | private | Visibility for the new artifact. Defaults to the source artifact's current visibility. |
--share <email> | repeatable string | Invite a person to the new artifact. May be passed multiple times. |
--share-with <emails> | comma-separated string | Same as repeated --share, in one flag. |
--json | boolean | Write the copy result and selected source version as one JSON value. |
Append @<version> to copy a retained historical version. Without it, the command copies the current version. The new artifact starts at version 1 without discussions. People invited to the source are not carried over; only addresses passed with --share or --share-with are invited to the copy.
share
$ dsp share [shortId]Change an artifact's visibility and add or remove invited people.
| Flag | Value | Description |
|---|---|---|
--visibility <level> | public | company | private | New visibility level. |
--add-users <emails> | comma-separated string | Invite these email addresses. |
--remove-users <emails> | comma-separated string | Remove these invited email addresses. |
--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). |
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. |
list
$ dsp listBrowse artifacts in your organization without a text query.
| Flag | Value | Description |
|---|---|---|
--author <a> | repeatable string | Filter by author. Each value can be an email, user ID, or me. Multiple values are ORed. me requires a user-scoped credential – passing it under an organization API key is rejected. |
--visibility <list> | comma-separated public | company | private | Filter by visibility. Only private artifacts you created 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. |
--limit <n> | integer 1–100 | Max rows to return. Defaults to 50. |
--json | boolean | Write the stable JSON response. |
Output is one row per line on stdout (shortId vN name url). When more pages are available, stderr prints a ready-to-run continuation command while stdout stays clean for pipes.
search
$ dsp search [query]Search artifact names, or search exact source text when you pass --in.
| Flag | Value | Description |
|---|---|---|
--in <shortId> | shortId or shortId@version | Search exact source text inside one artifact. Append a version to pin the search. |
--cursor <token> | opaque string | Continue an organization-wide name search. Cannot be used with --in. |
--offset <bytes> | non-negative integer | Continue a source search from this UTF-8 byte offset. Requires --in. |
--limit <n> | integer 1–100 | Maximum results. Scoped source search returns at most 50 matches per page. |
--json | boolean | Write the stable JSON response. |
Without --in, search matches artifact names. With --in, it finds literal source text and returns byte offsets, line hints, and bounded context. Continuation commands pin the artifact version so later updates cannot mix results from different versions.
find
$ dsp find [query]Deprecated compatibility command. Use dsp list to browse or dsp search to search.
find keeps the previous optional-query behavior for existing scripts and prints a migration notice to stderr. New scripts should use list or search.
get-metadata
$ dsp get-metadata [shortId]Print artifact metadata, retained versions, the current heading outline, and open comment threads as JSON.
The command has no command-specific flags. Sections you cannot read are omitted. Use dsp read for bounded source context.
dsp get-metadata <shortId> returns artifact metadata, retained versions, the heading outline, and open threads when permitted. It replaced the former dsp get <shortId> --include versions command.
read
$ dsp read [shortId]Print one bounded UTF-8 source range. Pin a version by appending @ and a number, e.g. dsp read abc123@2.
| Flag | Value | Description |
|---|---|---|
--offset <bytes> | non-negative integer | Zero-based UTF-8 byte offset. Defaults to 0. |
--limit <bytes> | integer 4–262144 | Maximum bytes returned. Defaults to 65536. |
--json | boolean | Write content and continuation metadata as JSON. |
Without --json, stdout contains only source text. Progress and the version-pinned continuation command go to stderr.
edit
$ dsp edit [shortId]Publish a new version by replacing one exact, unique source passage.
| Flag | Value | Description |
|---|---|---|
--base-version <n> (required) | positive integer | Current version that the edit is based on. |
--old <text> | string | Exact source passage to replace. Use either this flag or --old-file. |
--old-file <path> | path | Read the exact source passage from a UTF-8 file. Useful for multiline text. |
--new <text> | string | Replacement text. An empty string deletes the old passage. Use either this flag or --new-file. |
--new-file <path> | path | Read replacement text from a UTF-8 file. |
--json | boolean | Write the stable JSON response. |
The old passage must occur exactly once. Both values are limited to 262144 UTF-8 bytes. If a newer version was published, inspect that version with read or scoped search, reconcile the change, and retry with its version number.
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 published. markdown converts an HTML artifact to Markdown. |
export is the complete-file path for local CLI workflows. Remote MCP uses bounded read instead.
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 – email code, single sign-on device flow, or API key.
| Flag | Value | Description |
|---|---|---|
--email <email> | string | Email address. Required for email-code or single sign-on in non-interactive runs; not used with --api-key. |
--code <code> | 6-digit string | Email code. 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. |
mcp
$ dsp mcpStart the MCP server over stdin/stdout. Your agent starts this process – you don't run it yourself. See MCP server for host configuration.
No additional flags. The server's behavior depends on whether the CLI has a saved credential. It gets agent identity from the connected MCP client's name and version. See MCP tools.
Authentication
The CLI reads (in order):
DISPLAYDEV_API_KEY– environment variable. Highest precedence.- The saved session written by
dsp login.
Set DISPLAYDEV_ACTOR_TYPE (human or agent) and DISPLAYDEV_ACTOR_NAME to declare actor identity once across regular CLI invocations, equivalent to passing --actor-type and --actor-name. 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. dsp mcp ignores these settings and uses the connected MCP client's identity.
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.