DocsHTML ArtifactsCLI setup & workflow

HTML Artifacts CLI

Capability guideCLI 1.8.2Python 3.9+

Install the HTML Artifacts capability, then create and maintain static, versioned HTML without invoking an LLM. Artifacts stay private until a command explicitly changes visibility or creates a pinned capability link.

1. Install the CLI and this capability

Install the standalone command-line interface, then immediately start guided setup:

npm install --global @higantic/cli && higantic setup

Setup confirms the CLI and reviews every public capability with [Y/n] defaulting to Yes.

Or install only the HTML Artifacts instructions and references directly:

npx --yes skills add Aneaire/higantic-skills --skill higantic-html-artifacts --global

Separate installations

npm installs the application. npx skills installs agent instructions and references. Updating or removing one does not update or remove the other.

Command runbook

Verify the shared CLI

Confirm that the dedicated CLI installation exposed the shared HiGantic launcher.

Run

higantic setup

Expected

CLI 1.8.2 ready

If it fails

If the command is not found, run npm list --global @higantic/cli, ensure the npm global binary directory is on PATH, open a new terminal, and retry.

2. Authorize artifact access

higantic auth login
higantic doctor

Sharing is not selected by default

The high-trust html_artifacts:share permission starts unchecked. Request and approve it only when the CLI needs to publish an HTML page or manage a pinned link.

Use stable identifiers

Give repeatable workflows an externalId and use upsert. This prevents duplicate artifacts and makes retries deterministic.

3. Choose a page

higantic pages list
higantic pages create --label "Release reports" --idempotency-key "release-reports-page"

4. Create or update an artifact

higantic artifacts upsert   --page-id PAGE_ID   --external-id "release:weekly-report"   --title "Weekly release report"   --summary "Current release health and decisions"   --html-file ./report.html

Upsert reads the current artifact first and sends revision and metadata preconditions. If another writer changed it, the CLI returns exit code 3 and tells you to reconcile instead of overwriting newer work.

5. Inspect revisions and open the owner URL

higantic revisions list --page-id PAGE_ID --artifact-id ARTIFACT_ID
higantic url --page-id PAGE_ID --artifact-id ARTIFACT_ID

Add a revision or restore an older one

higantic revisions append --page-id PAGE_ID --artifact-id ARTIFACT_ID --html-file ./report.html
higantic revisions restore --page-id PAGE_ID --artifact-id ARTIFACT_ID --revision 2

Embed an existing managed image

Embed a previously returned higantic-asset://ASSET_ID reference directly. Use the separate Managed Assets skill to find, upload, inspect, publish, privatize, or delete images.

Publish only with explicit confirmation

higantic visibility set   --page-id PAGE_ID   --artifact-id ARTIFACT_ID   --visibility public   --confirm-public-sharing

Public visibility follows the current revision

Anyone can open the stable public URL while visibility is public. Updating its current revision also requires the sharing scope and explicit public-write confirmation.

Use HTML Artifacts in CI

higantic pages create   --label "CI reports"   --idempotency-key "ci:reports-page"

higantic artifacts upsert   --page-id PAGE_ID   --external-id "ci:release-report"   --title "Release report"   --html-file ./report.html

Reuse an idempotency key only for an identical create request. Use a page-unique external ID for artifact lookup and upsert. Conflict exit code 3 means another writer won; read, reconcile, and retry.

For the route and scope contract, see the Direct HTML Artifacts API.