HTML publish CLI

html-publish uploads and reads private HTML documents through a protected HTTP service. It uses Node.js 24 built-ins and has no runtime dependencies.

Install

Node.js 24 or newer is required.

npm install --global @akshay3001/html-publish

This installs the html-publish command.

Configure

Set the service origin and Cloudflare Access service token in the shell that runs the CLI:

export HTML_PUBLISH_ORIGIN="https://your-artifact-host.example"
export HTML_PUBLISH_CF_ACCESS_CLIENT_ID="your-client-id"
export HTML_PUBLISH_CF_ACCESS_CLIENT_SECRET="your-client-secret"

HTML_PUBLISH_ORIGIN must contain only an HTTPS origin. A path, query, fragment, or embedded credential is not accepted. HTTP is accepted only for a loopback test server.

The CLI sends the token as request headers. It does not write credentials to disk or include them in output.

Migrate existing machines

Rename these variables on each machine:

| Old name | New name | | --- | --- | | HTML_COMMUNICATION_ORIGIN | HTML_PUBLISH_ORIGIN | | HTML_COMMUNICATION_CF_ACCESS_CLIENT_ID | HTML_PUBLISH_CF_ACCESS_CLIENT_ID | | HTML_COMMUNICATION_CF_ACCESS_CLIENT_SECRET | HTML_PUBLISH_CF_ACCESS_CLIENT_SECRET |

The CLI accepts the old names as migration aliases. When both names exist, the new name takes precedence. Remove the old exports after you update a machine.

Use

html-publish health
html-publish upload ./plan.html --scope agents
html-publish upload ./plan.html --scope agents --name stable-plan.html
artifact_url=$(html-publish upload ./plan.html --scope agents)
html-publish fetch "$artifact_url" > ./artifact.html

upload requires a nonempty kebab-case .html filename and a kebab-case scope. The HTML file can contain at most 512 KiB. A successful upload prints only the canonical document URL to stdout.

fetch accepts only a /view/{scope}/{filename} URL from the configured origin. Redirect stdout to a file or pipe it to another program. The command refuses to write active HTML to a terminal. It stops after 30 seconds and rejects a response larger than 512 KiB.

The upload command accepts a response with either a url or fileUri field.

Develop

npm install
npm run validate
npm pack --dry-run

npm run validate checks types, runs tests, and creates the JavaScript files in dist.

Publish

The publish-html-publish.yml GitHub Actions workflow publishes manually with npm trusted publishing. Configure the @akshay3001/html-publish package with this trusted publisher:

Organization or user: akshay3001
Repository: agents
Workflow: publish-html-publish.yml
Allowed action: npm publish

Merge the package version change before you run the workflow. After the first trusted publish succeeds, disable token-based publishing in the npm package settings and revoke the old automation token.

The repository is private. npm trusted publishing removes the long-lived publish token, but npm does not create provenance attestations for a package built from a private repository.