ASTRODOCK documentation Home GitHub

Pages

Publishing a page (CLI & agents)

Publish a document or static bundle to Pages from the terminal — or hand the same workflow to an AI agent. There's no git, build, or deploy step: uploads are live immediately. This page is self-contained; an agent needs only a pages-scoped token and these instructions.

Mental model

  • A page is a flat-or-nested set of files served at https://pages.<domain>/<pageId>/.
  • The pageId is a random 12-character string assigned at creation. Save it — it's the handle for updating the page later.
  • One file is the entry file (default index.html); a non-HTML entry (e.g. a PDF) turns the link into a file share.
  • A page is public, passkey-protected, or behind platform login — see Pages.

Get a token

In the dashboard, open Tokens → New token and grant the pages scope. A pages-scoped token can create, update, and delete pages and files — and nothing else (it can't touch apps, users, or other tokens). Then point the CLI at your platform:

export ASTRODOCK_URL="https://admin.example.com"
export ASTRODOCK_TOKEN="tk_your-pages-scoped-token"

Treat the token like a password

Pass it through the environment, never in page content or chat output. If an agent is publishing for you, give it a pages-scoped token — never your admin login.

Publish with the CLI

# A folder (index.html + assets, nested paths preserved)
astrodock pages push ./build --title "Q3 Dashboard"

# A single HTML file → a public page
astrodock pages push report.html --title "Board Report"

# Share one file (the file becomes the entry automatically)
astrodock pages push deck.pdf --title "Pitch Deck" --generate-passkey

# Protect with platform login, restrict later in the dashboard
astrodock pages push ./build --title "Team Wiki" --access platform

# Just print the URL (for scripting)
astrodock pages push report.html --quiet

On success the CLI prints the page URL and the pageId (and the passkey, if one was generated). It never prints your token.

Options

FlagMeaning
--titlePage title (defaults to the folder/file name).
--accesspublic · passkey · platform.
--generate-passkey / --passkey KProtect with a generated or chosen passkey.
--dataEnable the saved-data blob: shared or per-user.
--entryEntry file (default index.html, else the only/first file).
--page-idUpdate an existing page instead of creating a new one.
--quietPrint only the resulting URL.

Update, don't duplicate

To publish a new revision of the same document, re-upload to its pageId — the link stays the same. Re-uploading a filename replaces that file.

astrodock pages push ./build --page-id k3v9x2mqa7f1

List & remove

astrodock pages list           # pageId, title, access, data, status, views
astrodock pages rm <pageId>     # delete a page and all its files (permanent)

Prefer deactivating to deleting

To take a page offline without losing it, flip it to inactive in the dashboard (it 404s until reactivated). Delete is permanent.

Verify after publishing

Fetch the link yourself — expect 200 for a public page, or 401 for the no-key link of a protected one. Then report the link, pageId, and passkey (if any) to whoever asked.

curl -s -o /dev/null -w "%{http_code}\n" "https://pages.example.com/<pageId>/"

File rules

  • Names use letters, digits, ., -, _ and / for folders. No .., no leading slash, no spaces or leading dots.
  • Reference assets by their page-relative path (img/logo.png), and upload them at that path.
  • Up to 20 files per upload request (the CLI batches automatically) and 200 MB per file.
  • No server-side code — files are served as-is; JavaScript runs in the visitor's browser.

Not using the CLI?

Every action maps to an admin API call with your token as a Bearer credential:

POST   /admin/pages                      # create  { title, accessMode, generatePasskey?, dataMode? }
POST   /admin/pages/:id/files            # multipart upload (field "files"; optional "paths" JSON array)
PATCH  /admin/pages/:id                  # title / isActive / entryFile / accessMode / passkey / allowlist
POST   /admin/pages/:id/generate-passkey # rotate the passkey
GET    /admin/pages   ·   GET /admin/pages/:id   ·   DELETE /admin/pages/:id

Next steps