Artifact Share

Artifact Share CLI reference

CLI version: @artifactshare/cli 0.15.3 · Generated: 2026-10-11

A public, machine-friendly guide to sharing, updating, reading, and organizing artifacts from a terminal.

Introduction and authentication

Node.js 22.19 or newer is required. Start with npm exec --yes --package=@artifactshare/cli -- artifactshare init --json, complete browser sign-in, or import a token for CI with profiles import-token. Use login --preset agent to restrict an agent to one selected project. A new profile defaults to unrestricted access; an existing profile keeps its previous preset. API-only publisher credentials require a normalized device_name and explicit browser choice to create or continue a client. Duplicate names require continuation or another device_name; names cannot be edited during approval. Publisher versions refresh content and live viewers without changing human activity order, feeds or unread signals. Version history marks scheduled updates. API updated_at remains the actual mutation time. Publisher credentials create private HTML/Markdown files or static sites in home and manage artifacts created by or assigned to their client, even after sharing or moving within the workspace. With a publisher credential, single-file updates require expected_version; static-site deltas use base_version and delete_path. With a publisher credential, the exact download endpoint returns source bytes for single files and a manifest for static sites; individual asset downloads are denied. With a publisher credential, readback includes visibility and is metadata-only for static sites. Publisher credentials can delete these artifacts; with a publisher credential, POST/PATCH edit accepts only retain_versions (positive integer or null); pruning deletes eligible old versions permanently. On artifacts created by or assigned to a publisher client, retention counts only published versions added with publisher credentials, including earlier clients, and keeps every other version. This also applies to unrestricted owner edits. The newest N publisher versions and every current version are kept; drafts do not count. Unmanaged artifacts continue to count all published versions. Owner unrestricted credentials or a browser session can POST /api/cli/artifacts/:id/adopt with publisher_client_id from whoami/doctor. Audited assignment replaces the previous client's access. With a publisher credential, list, resolve, comments, audience edits, move, projects, append and upsert remain denied. CLI publisher login/resume and publishing/download workflows are unsupported; doctor reports the client scope. Use --profile to keep credentials separate, logout to revoke a browser-authenticated CLI session, and Settings → Tokens to revoke an API token.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

Basic operations

Use share for a file, folder, or static site; update to keep the same URL; open or artifacts get to read; download to save locally; comments for review; projects for organization; profiles and config for accounts and settings; and skills for agent setup. REST API only: POST /api/shareables/:id/versions?artifact_kind=static_site accepts base_version=v1 and repeated delete_path values, for example delete_path=data/old.parquet. Sent files replace matching paths; remaining files are inherited. The base must be current (409 version_conflict otherwise) and supplies the expected version, including for agents. An explicit expected_version must match it. Deletion requires a base; sending and deleting the same path is invalid. A delete-only update must retain index.html or index.md. Version bytes describe the complete file list; workspace quota counts unique stored objects. CLI update has no inheritance flags. Browser share pages pass their URL fragment (#) to HTML, Markdown, and static-site frames, follow changes inside them, and include it in Copy link for sharing filtered views or headings. Only a static site’s entrypoint updates the share fragment; subpages leave it unchanged. CLI local preview is unchanged.

Command reference

The command surface below is generated from the public CLI help. Usage and accepted options are rendered from the generated surface snapshot.

All public commands

append

Append a local UTF-8 file to an existing single-file HTML or Markdown artifact.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare append <artifact-id-or-url> ./section.md --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare append <OPTIONS> <artifactIdOrUrl> <path>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

artifacts

Browse, read, and delete artifacts.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare artifacts [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

artifacts delete

Alias of delete: permanently delete an artifact.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare artifacts delete <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

artifacts get

Read an artifact and its metadata.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare artifacts get <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --offset · --include

artifacts list

List artifacts you can access, including project or home results.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare artifacts list <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --project-id · --home · --query · --cursor

changelog

Show CLI release notes.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare changelog <OPTIONS>

Options

--help · --version · --json

comments

Work with comments on an artifact.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

comments delete

Delete a comment message.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments delete <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --thread-id · --message-id

comments edit

Edit a comment message.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments edit <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --message-id · --body

comments list

List comment threads and messages.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments list <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

comments post

Post a comment or reply. Quote positions stay unchecked until a viewer resolves the exact context.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments post <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --body · --reply-to · --quote · --quote-before · --quote-after · --agent

comments reopen

Reopen a resolved comment thread.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments reopen <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --thread-id

comments resolve

Resolve a comment thread.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare comments resolve <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --thread-id

config

Inspect and change local CLI settings.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare config [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

config get

Read a setting at user, repository, or effective scope.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare config get home_audience --scope effective --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare config get <OPTIONS> [<key>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --scope

config set

Save a setting at user or repository scope.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare config set home_audience private --scope user --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare config set <OPTIONS> <key> <value>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --scope

config unset

Remove a setting at user or repository scope.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare config unset <OPTIONS> <key>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --scope

delete

Permanently delete an artifact.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare delete <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

doctor

Check token storage, authentication, configuration, and connectivity.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare doctor <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

download

Download an artifact to a local path.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare download <OPTIONS> [<artifactIdOrUrl>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --project-id · --output · --force

edit

Edit artifact title, visibility, grants, or destination.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare edit <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --title · --visibility · --link-expires-at · --retain-versions · --no-link-expiry · --grant-email · --revoke-email · --project-id · --home

--visibility <visibility> private, workspace, project, or link (project requires placement in a project)

--retain-versions <retain-versions> N or all (owner only). Keeps the latest N versions; publisher-managed artifacts count only publisher versions and keep all versions people added. Older eligible versions are permanently deleted; all clears the limit.

init

Detect the agent, install its skill, and start setup.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare init --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare init <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --project-id · --dry-run

login

Authorize the CLI with unrestricted or project-scoped agent access.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare login --profile agent --preset agent --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare login <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --preset · --project

logout

Revoke and remove a saved credential.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare logout <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

move

Move an artifact to a project or home.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare move <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --project-id · --home

open

Read an Artifact Share URL and prepare the CLI skill when needed.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare open <artifact-id-or-url> --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare open <OPTIONS> <artifactIdOrUrl>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

preview

Preview a local file with the product viewer look and annotate it.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

preview done

Report batch outcomes from stdin JSON, idempotent per generation.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview done <OPTIONS> [<file>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --stdin · --session

preview next

Return every undelivered annotation batch to the agent.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview next <OPTIONS> [<file>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --wait · --session

preview reply

Append a reply to an annotation thread without changing state.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview reply <OPTIONS> [<file>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --thread · --body · --session

preview start

Serve a local .md or .html file for annotation. Invoked as preview <file>.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview start <OPTIONS> [<file>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --no-open

preview stop

Stop a live preview session; annotations stay saved.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare preview stop <OPTIONS> [<file>]

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --session · --force

profiles

Manage named authentication profiles.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare profiles [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

profiles delete

Delete a named profile.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare profiles delete <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

profiles import-token

Import a CI or manually issued token into a profile.

Example
printf '%s' "$ARTIFACTSHARE_TOKEN" | npm exec --yes --package=@artifactshare/cli -- artifactshare profiles import-token --profile ci --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare profiles import-token <OPTIONS>

Options

--help · --version · --json · --base-url · --profile · --allow-plaintext-token-store · --insecure-localhost · --force

profiles list

List saved profiles.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare profiles list <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

profiles use

Select the active profile.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare profiles use <OPTIONS> <name>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

projects

Manage projects.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare projects [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

projects create

Create a project.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare projects create <OPTIONS> <name>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --description · --visibility

projects edit

Edit project details, audience, or archive state.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare projects edit <OPTIONS> <id>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --name · --description · --visibility · --add-email · --remove-email · --archive · --unarchive

projects list

List projects available to you.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare projects list <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

resolve

Resolve a URL, ID, or other Artifact Share value.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare resolve <OPTIONS> <value>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

share

Share a local file, folder, or static site. Profiles logged in with login --preset agent must also pass --expected-version when republishing with --key (see Failures and recovery).

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare share ./report.html --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare share <OPTIONS> <path>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --project-id · --project · --home · --visibility · --link-expires-at · --no-link-expiry · --no-slack-notify · --grant-email · --key · --expected-version

skills

Manage the installed Artifact Share agent skill.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills [COMMANDS] <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

skills ensure

Ensure the skill is installed for a detected tool.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills ensure <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --tool · --scope · --dry-run

skills install

Install the skill for a selected tool.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills install <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --tool · --scope · --dry-run · --force

skills list

List installed skill targets.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills list <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

skills remove

Remove an installed skill.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills remove <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --tool · --scope · --dry-run

skills update

Update an installed skill.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare skills update <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --tool · --scope · --dry-run · --force

update

Upload a new version behind an existing share URL. Profiles logged in with login --preset agent must also pass --expected-version (see Failures and recovery). Optional --label adds an immutable 1–80-code-point note, normalized to NFC with outer Unicode spaces trimmed; internal spacing and case stay unchanged. Letters, marks, numbers, punctuation, symbols, spaces, and joined emoji are allowed. Omission creates an unlabeled version. Successful JSON includes the stored label at data.version.label, or null when omitted. data.version.number matches the Viewer version number (v{number}); older servers may omit it. Read version history with artifacts get --include versions. Empty labels, control characters, and invalid, invisible-only, or repeated --label values fail locally with validation_failed before authentication.

Example
npm exec --yes --package=@artifactshare/cli -- artifactshare update <artifact-id-or-url> ./report.html --expected-version <version-id> --json

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare update <OPTIONS> <artifactIdOrUrl> <path>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost · --label · --expected-version

whoami

Show the active account and workspace.

Usage

npm exec --yes --package=@artifactshare/cli -- artifactshare whoami <OPTIONS>

Options

--help · --version · --json · --base-url · --token · --profile · --allow-plaintext-token-store · --insecure-localhost

JSON output and exit codes

With --json, piping, or another non-interactive invocation, successful results go to stdout as a common envelope with schema_version: 2, ok: true, command, and data. Failures go to stderr with schema_version: 2, ok: false, command, and error. Exit code 0 means success, 1 means a command failure, and 130 means cancellation. An auth_required response includes the verification URL and user code; approve it, then rerun the same command.

Projects, home, audience, and settings

edit accepts --visibility private|workspace|project|link. Project visibility requires the artifact to be in a project after the edit; use --project-id <id> in the same request if needed. An explicit --visibility project at home (including --home) is refused without changes. Moving a project-visible artifact home makes it private only when project visibility is not explicitly requested. A project destination uses the project audience. When share has no destination, it posts to home. Choose home_audience by purpose: use user scope for a personal safe default in this CLI environment, repository scope only for a policy agreed by all participants, and explicit --visibility for one post. Confirm the result with config get home_audience --scope effective --json. home_audience is the canonical setting: private means only you, and workspace means everyone in the workspace. Store repository settings in .artifactshare/config.json and user settings in the user config directory. Home resolution checks repository home_audience, repository default_artifact_visibility, user home_audience, user default_artifact_visibility, then the product default workspace. default_artifact_visibility is only a compatibility alias. default_project_visibility is an independent default for projects create. --grant-email adds an individual project share recipient; it does not implicitly change project visibility.

Failures and recovery

For auth_required or token_invalid, run login or import a valid profile token and rerun the same command. For validation_failed, check usage and options. For target_not_found, resolve the URL or ID again. For self_upload_disabled, sign in with Google or Microsoft and rerun the same command. For network_failed, check the base URL and retry without changing the destination. For expected_version_required after login --preset agent, pass data.version.id from the previous successful share or update output as --expected-version when retrying update or share --key. If that output is unavailable, for single-file HTML and Markdown artifacts, artifacts get <target> --json returns the current version as data.version_id. For static sites, download <target> --json returns it as data.version.id. Check the returned current content (data.content, or the downloaded files for static sites) and reapply your changes to it if it differs from what you edited. Pass the returned value as --expected-version.

Create an API token for non-interactive use

If you use the CLI in CI or another environment without browser sign-in, create an API token.

Create an API token

Use the connect guide to choose an integration, the Share with AI guide to learn how to ask an agent, the updates page for product changes, and the npm package page for installation details.