@automintech/htmlshare

CLI for htmlshare — share self-contained HTML artifacts at clean URLs. Authenticate with a Personal Access Token; deploy from the command line or from an AI agent via the bundled MCP server.

Install

# Run without installing (recommended for one-off use)
npx @automintech/htmlshare <command>

# Install globally to get the `htmlshare` binary
npm install -g @automintech/htmlshare
htmlshare <command>

Scoped package note: npx htmlshare does NOT resolve to this package unless it is globally installed. Always use npx @automintech/htmlshare for one-off use.

Auth

Generate a Personal Access Token in the htmlshare Settings page: https://www.htmlshare.ca/app/settings

Then store it with:

# Preferred: read from stdin (token never appears in shell history or `ps` output)
echo "hs_your_token" | npx @automintech/htmlshare login -

# Or pass directly (argv visible to `ps` — avoid on shared machines)
npx @automintech/htmlshare login hs_your_token

The token is saved to ~/.htmlshare/config.json (mode 0600).

Alternatively, set the HTMLSHARE_TOKEN environment variable (takes precedence over the config file):

export HTMLSHARE_TOKEN=hs_your_token

Commands

login

npx @automintech/htmlshare login <token>   # argv (caution on shared machines)
npx @automintech/htmlshare login -         # read token from stdin (preferred)

whoami

Verify your token and display identity info.

npx @automintech/htmlshare whoami

deploy

Deploy an HTML file and receive a shareable URL.

npx @automintech/htmlshare deploy report.html
npx @automintech/htmlshare deploy report.html --title "Q3 Rollout"
npx @automintech/htmlshare deploy report.html --slug q3-rollout --expires 7d
npx @automintech/htmlshare deploy -                 # read HTML from stdin
cat report.html | npx @automintech/htmlshare deploy -

• --slug <s> — custom vanity slug (3–64 chars: letters, numbers, dashes, underscores). Reusing a slug you own uploads a new version.
• --expires <e> — 1h, 1d, 7d, 30d, never, or a positive integer of seconds.

slug

Change the custom slug of an existing document you own. The previous URL stops working immediately; the content is served at the new slug.

npx @automintech/htmlshare slug old-slug new-slug

expires

Change the expiration (TTL) of an existing document without re-uploading (no new version is created).

npx @automintech/htmlshare expires my-slug 1d        # 1h | 1d | 7d | 30d
npx @automintech/htmlshare expires my-slug never     # clear the expiry
npx @automintech/htmlshare expires my-slug 3600      # raw seconds

list

List your HTML artifacts with optional title search.

npx @automintech/htmlshare list              # all documents
npx @automintech/htmlshare list "rollout"   # title filter (case-insensitive)
npx @automintech/htmlshare list --json       # JSON array output
npx @automintech/htmlshare list --limit 5    # first 5; hidden count logged to stderr

fetch

Retrieve the HTML content of a document.

# By exact 10-character slug (direct, no list call)
npx @automintech/htmlshare fetch abcde12345

# By title query (0 matches: shows full list; 1 match: fetches; >1: shows candidates)
npx @automintech/htmlshare fetch "rollout plan"

# Write to a file instead of stdout
npx @automintech/htmlshare fetch "rollout plan" --out report.html

token list

List your API tokens (name, prefix, created date, last used).

npx @automintech/htmlshare token list

token revoke

Revoke a token by its prefix (visible from token list).

npx @automintech/htmlshare token revoke hs_a1b2c3d4

Global flags

| Flag | Effect | |------|--------| | --verbose, -v | Trace each HTTP request/response to stderr. The Authorization header is redacted (Bearer [REDACTED]) — the token is never printed. Works with any command. |

npx @automintech/htmlshare list --verbose
# > GET https://…/api/documents
# > authorization: Bearer [REDACTED]
# < 200 https://…/api/documents

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | User / validation error (invalid token, not found, ambiguous query) | | 2 | Network / infrastructure error (connection refused, timeout) |

MCP server

The MCP server (htmlshare-mcp) ships in the same package and exposes these tools:

| Tool | Description | |------|-------------| | htmlshare_deploy | Deploy a self-contained HTML file or inline string, optionally with a custom slug and expires TTL. Returns view + download URLs. | | htmlshare_reslug | Change an existing document's custom slug. | | htmlshare_set_expiry | Change an existing document's expiration (TTL) without re-uploading. | | htmlshare_list | List your artifacts, optionally filtered by title substring or exact slug. | | htmlshare_fetch | Fetch artifact content by slug (no token needed) or by title query. Content >200 KB is saved to a temp file rather than returned inline. |

Configure your MCP client

Add the following to your MCP client configuration (e.g. Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "htmlshare": {
      "command": "npx",
      "args": ["-y", "--package=@automintech/htmlshare", "htmlshare-mcp"],
      "env": {
        "HTMLSHARE_TOKEN": "${HTMLSHARE_TOKEN}"
      }
    }
  }
}

Token hygiene — important: never put the literal token value in your MCP config file. Config files are often synced to dotfiles repos or version control, which would expose your token. Instead:

1. Add export HTMLSHARE_TOKEN=hs_your_token to your shell profile (~/.zshrc, ~/.bashrc, etc.) — a file that is not synced.
2. Reference it in the config as "${HTMLSHARE_TOKEN}" (the shell will expand it when launching the server process).
3. Never commit HTMLSHARE_TOKEN to a dotfiles repository.

Tool details

htmlshare_deploy

• path (string, optional) — Absolute path to an HTML file on disk.
• html (string, optional) — Inline HTML content to deploy.
• title (string, optional) — Display title for the artifact.
• slug (string, optional) — Custom vanity slug (3–64 chars). Reusing a slug you own uploads a new version.
• expires (string, optional) — 1h, 1d, 7d, 30d, never, or a positive integer of seconds.
• One of path or html is required.

htmlshare_reslug

• slug (string, required) — The document's current slug.
• newSlug (string, required) — The new vanity slug (3–64 chars).

htmlshare_set_expiry

• slug (string, required) — The document slug.
• expires (string, required) — 1h, 1d, 7d, 30d, never, or a positive integer of seconds.

htmlshare_list

• query (string, optional) — Title substring or exact 10-character slug. Omit to list all.

htmlshare_fetch

• slug (string, optional) — Exact 10-character slug. Uses the public view domain; no token required.
• query (string, optional) — Title substring or slug for discovery (requires token).
• out (string, optional) — File path to write content to. If omitted and content exceeds 200 KB, content is written to a temp file and the path is returned.
• One of slug or query is required.

Endpoint overrides

| Env var | Default | Purpose | |---------|---------|---------| | HTMLSHARE_API_URL | https://kindhearted-puma-793.convex.site | Convex HTTP actions (deploy/list/admin) | | HTMLSHARE_VIEW_URL | https://view.htmlshare.ca | View domain (content fetch) |