@clawmapper/publish

CLI for publishing self-contained HTML pages to a publish-service instance.

Install

npm install -g @clawmapper/publish

Configure

Run once to save your server URL and API key:

publish configure
# Base URL: https://your-service.example.com
# API key:  pub_live_xxxx...

Config is saved to ~/.publish.json with permissions 600.

Commands

publish upload <file>

Publish an HTML file. Prints the page URL on success.

# Public — anyone with the link can view
publish upload report.html --public --title "Q4 Report"

# Password protected
publish upload report.html --password "hunter2" --title "Internal Report"

# Restricted to specific emails or domains
publish upload report.html --allow "[email protected],[email protected]"
publish upload report.html --allow "*@corp.com"
publish upload report.html --allow "[email protected],*@corp.com"

# Update an existing page (preserves its auth settings unless flags are given)
publish upload report-v2.html --slug aB3xY7qZ

Options

| Flag | Description | |---|---| | --title <title> | Human-readable page title | | --public | No authentication | | --password <pw> | Protect with a shared password | | --allow <list> | Comma-separated emails and/or *@domain.com wildcards | | --slug <slug> | Update an existing page instead of creating a new one |

If no auth flag is given, the CLI will prompt interactively.

publish list

List all published pages.

publish list

publish open <slug>

Open a page in your default browser.

publish open aB3xY7qZ

publish auth <slug>

Show or update the auth settings for a page.

# Show current settings
publish auth aB3xY7qZ

# Make public
publish auth aB3xY7qZ --public

# Change password
publish auth aB3xY7qZ --password "newpassword"

# Replace the allowed list entirely
publish auth aB3xY7qZ --set "[email protected],*@corp.com"

# Add to the allowed list
publish auth aB3xY7qZ --add "[email protected]"

# Remove from the allowed list
publish auth aB3xY7qZ --remove "[email protected]"

publish delete <slug>

Delete a page (prompts for confirmation).

publish delete aB3xY7qZ

HTML requirements

Pages must be fully self-contained — all CSS, JavaScript, fonts, and images must be either inlined or hosted at a publicly accessible URL. Private URLs (e.g. private GitHub raw links) will not load for viewers who don't have access.

Auth modes

| Mode | How it works | |---|---| | public | Anyone with the URL can view | | password | Visitors enter a shared password; session lasts 7 days | | email_list | Visitors enter their email; a one-time magic link is sent if they're on the list | | email_domain | Same as above but access is granted to an entire domain (e.g. *@corp.com) |

Email-based auth requires the server to be configured with a Resend API key. If it isn't, visitors will see a clear error rather than a broken flow.