CLIAI Agents

AI Agents

Use the CLI when an AI agent creates a report, runbook, OpenAPI spec, or review artifact that should be shared as a private internal page.

If you use Codex or Claude Code, you can instead install the internalpage plugin once and publish with a natural-language request. Use the CLI workflow below when you want explicit local commands, CI-friendly automation, or support for an agent without the plugin.

The pattern is simple:

  1. The agent writes a local .html, .md, .yaml, or .json file.
  2. You save a personal API token once with internalpage login.
  3. The agent runs @internalpage/cli without seeing the raw token.
  4. internalpage returns a private viewer URL for the workspace.
  5. Future runs use the same publish --slug command to update the page.

Token setup

Create a personal API token in your workspace settings, then save it once before asking the agent to publish files.

npx @internalpage/cli login

The CLI stores the token in the OS config directory and reuses it for later commands. This is the easiest setup for local AI coding agents because the prompt can mention only npx @internalpage/cli publish ..., not the token.

For non-interactive setup, pass the token on stdin so it does not appear in shell history.

printf '%s' "$IP_TOKEN" | npx @internalpage/cli login --token-stdin

Use a direct IP_TOKEN=... environment variable for CI jobs or short-lived one-off shells. IP_TOKEN overrides the saved token.

Publish a generated file

Ask the agent to write the artifact to disk first, then publish that file.

npx @internalpage/cli publish ./agent-report.md \
  --slug agent-report \
  --description "AI-generated release review"

The command prints the page ID, slug, and viewer URL. The CLI stores the page ID in .internalpage/config.json so the same slug updates the same page later.

Update the same page

Run the same command again. This keeps the private viewer URL stable while replacing the source content.

npx @internalpage/cli publish ./agent-report.md --slug agent-report

If an agent must target a specific page ID, use --page:

npx @internalpage/cli publish ./agent-report.md --page pg_xxx

Read before editing

When the agent needs to revise an existing page, read the current source into a local file first.

npx @internalpage/cli pull agent-report --output current-report.md

Then let the agent edit current-report.md and run publish --slug.

Prompt pattern

Give the agent a narrow publishing contract:

Write the final report to ./agent-report.md.
Do not include secrets or private credentials in the file.
Publish it with:
npx @internalpage/cli publish ./agent-report.md --slug agent-report
Return the internalpage viewer URL.

Before giving this prompt, run npx @internalpage/cli login once in the same user environment.

Agent instructions

For recurring use, add a short instruction block to your agent project config, such as AGENTS.md, CLAUDE.md, or Cursor rules. Keep the instruction focused on the CLI contract, not on raw credentials.

When publishing generated reports, docs, specs, or review artifacts:
 
- Write the final artifact to a local file first.
- Run `npx @internalpage/cli status --json` before publishing.
- If auth is missing, ask the user to run `npx @internalpage/cli login`.
- Publish with `npx @internalpage/cli publish <file> --slug <slug> --json`.
- Use the same slug for recurring updates.
- Return the viewer URL from the command output.
- Never include API tokens in prompts, generated files, command examples, or logs.

For Codex, put this in the repository AGENTS.md. For Claude Code, put it in CLAUDE.md. For Cursor, put it in a project rule. The same snippet works across agents because it only depends on the public CLI.

Guardrails

  • Use personal API tokens, not shared workspace tokens.
  • Save the token once with login for local agents.
  • Keep IP_TOKEN in CI secrets or short-lived shell environments only.
  • Prefer repeated publish --slug commands for recurring reports so shared links do not change.
  • Use workspace visibility for broad internal artifacts.
  • Review generated content before publishing if it may include customer data, credentials, or unreleased information.
Publish PagesPage File Types