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.

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 auth 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 update the same page ID instead of creating a new link.

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 auth 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 pages ..., 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 auth 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 pages create ./agent-report.md \
  --slug agent-report \
  --description "AI-generated release review"

The command prints the page ID, slug, and viewer URL. Save the page ID if the agent should update the same page later.

Update the same page

Use pages update after the first successful publish. This keeps the private viewer URL stable while replacing the source content.

npx @internalpage/cli pages update pg_xxx ./agent-report.md

You can also pass the viewer URL instead of the page ID:

npx @internalpage/cli pages update https://view.internalpage.com/w/acme/p/agent-report ./agent-report.md

Read before editing

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

npx @internalpage/cli pages read pg_xxx --output current-report.md

Then let the agent edit current-report.md and run pages update.

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 pages update pg_xxx ./agent-report.md
Return the internalpage viewer URL.

Before giving this prompt, run npx @internalpage/cli auth login once in the same user environment. For a first run, use pages create and ask the agent to report the returned page ID so future runs can call pages update.

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 auth status` before publishing.
- If auth is missing, ask the user to run `npx @internalpage/cli auth login`.
- Create a new page with `npx @internalpage/cli pages create <file> --slug <slug>`.
- Save and report the returned page ID and viewer URL.
- Update an existing page with `npx @internalpage/cli pages update <page-id> <file>`.
- Use page IDs as the canonical update target.
- 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 auth login for local agents.
  • Keep IP_TOKEN in CI secrets or short-lived shell environments only.
  • Prefer pages update 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.
OverviewCreate Pages