Pageship

Pageship is an HTML publishing service in development. This CLI checks a server's API compatibility, authorizes an installation through a browser, and identifies your personal workspace. It publishes HTML documents and revisions behind stable addresses. Private browser delivery requires the owner to sign in.

Requires Node.js 24.11 or newer.

npx pageship
npx pageship --help
npx pageship --version
npx pageship status --server http://localhost:8787
npx pageship --json status --server http://localhost:8787

status accepts an HTTP or HTTPS server base URL and checks the API major this CLI requires against the majors advertised by the server. Package versions do not determine API compatibility. The request times out after 10 seconds.

The --json flag is global and may appear before or after status, including on help, version, and invalid invocations. JSON mode writes one JSON value to stdout without human output or prompts. Like other flags, --json after the -- separator is treated as an argument. Interactive wizard and shell-completion options are available only in human mode.

• Exit 0: compatible server, help, or version.
• Exit 1: invalid arguments, network failure, or invalid server response.
• Exit 2: incompatible API major. The result explains whether the CLI or server needs updating, or the requested major is unsupported.

JSON status results contain ok, command: "status", status, requiredApiMajor, server, and message. status is compatible, client_too_old, server_too_old, or unsupported. The server object contains serverVersion, currentApiMajor, and supportedApiMajors. Failures contain ok: false and an error object with code and message; codes are usage_error, request_failed, or internal_error. Help and version use command: "help" and command: "version", respectively.

Browser authorization

Run pageship login --server https://api.example.com, open the displayed link on any machine, and approve the code using your invited GitHub account. Interactive terminals wait for approval. JSON and non-TTY calls return immediately with a link, code and completion arguments; then run pageship login --complete --server https://api.example.com. Run pageship whoami --server https://api.example.com to reuse the stored credential in a new process. Add global --json for structured results. Pending or denied authorization exits 2, success exits 0, request/storage failures exit 1, and interrupted waiting exits 130.

Credentials are plaintext JSON outside projects. POSIX uses an owner-only directory and 0600 files. Windows uses the current user's local app data and inherits user-profile permissions; the CLI does not configure Windows ACLs. PAGESHIP_CONFIG_DIR selects an absolute private directory. They are bound to the exact HTTPS server origin; HTTP is allowed only on loopback for development. Use login --restart for a new code. Address selection and publication are not required for authorization. No credentials appear in command output.

Publish HTML

Run pageship publish report.html --server https://api.example.com after login. Absolute file arguments work too. Add --json for structured success, source-path collisions and address choices. If publication fails after transfer, retry with the returned --idempotency-key. Reusing that key with the same input returns the same document; a different input produces a conflict. Ordinary path collisions never update or duplicate a document without an explicit choice.

In a terminal, select o <number> to open a matching document, r <number> to revise it, n to create a separate private document, or q to cancel. Opening and cancellation do not change published content. JSON returns candidates and resolutions containing complete follow-up command arguments. Run those arguments in another invocation to choose explicitly.

Use --new to create a separate document even when its source path matches. Use --revise <documentId> --expected-revision <revisionId> from a returned candidate to publish a revision. A concurrent publication returns revision_conflict and does not overwrite the newer revision. Revisions retain document identity, URL, visibility and old immutable content. An interrupted action returns next arguments including its operation key and selected target; repeat those with unchanged bytes. Explicit actions require a server that advertises support; an older server returns upgrade guidance before HTML upload.

The default per-file limit is 10,000,000 bytes, configurable by the server. The CLI checks it before upload. Source paths are relative to the file's Git root, containing working directory, or parent for outside-cwd non-Git files. Git origin URLs contribute a normalized, credential-free hashed context. No local manifest is required.

Generated address choices use --address-choice <choiceId> or --refresh-addresses; arbitrary subdomain input is not supported. An interactive terminal can select, refresh or cancel. JSON and non-TTY output never waits for a choice. Published results exit 0; unresolved choices, collisions, access and size failures exit 2; file/request/usage failures exit 1. See the repository's publishing contract for details.

Development

Install dependencies from the workspace root as described in the root README. From this directory:

pnpm run check
pnpm run build
node dist/cli.mjs --help
npm pack --dry-run

The CLI uses TypeScript and Effect v4's unstable CLI API. Effect and its Node platform package are pinned to matching release candidates. The shared generated API client is a workspace development dependency bundled into dist/cli.mjs. Installing the published CLI does not require the private workspace package or a checkout of this repository.

Revoke installation access

whoami --server <origin> shows this CLI installation's non-secret ID. JSON mode returns it in installation.id. Match that ID in the signed-in dashboard's CLI installations list and select Revoke access. The next protected request returns exit 2 with sign-in guidance; other installations remain authorized. Run login with the same server to authorize again explicitly.

License

UNLICENSED. No open-source license is granted.