Docs menu
Docs/Agents/Agent guide
View as Markdown

Agent guide

Interfold is built to be driven by coding agents. This page is the reference for an agent operating Interfold on a user’s behalf: the tools, the safe defaults, and the conventions that keep publishes correct and credentials protected.

If you are a human, this page still doubles as a concise operating checklist.

Machine-readable docs

Every page on this site is available as raw Markdown at a predictable URL, plus two aggregate files following the llms.txt convention:

  • /llms.txt — an index of every doc with one-line descriptions and links. Fetch this first to orient.
  • /llms-full.txt — the entire documentation set concatenated into a single file. Fetch once to load everything.
  • Raw per page — append the slug to /raw/. This page is at /raw/agents; the CLI reference is at /raw/cli; and so on.

All three are served as plain text so you can fetch and parse them directly:

curl https://docs.interfold.site/llms.txt
curl https://docs.interfold.site/raw/cli

Choose the CLI or MCP

The browser agent also exposes list_buckets, get_bucket, create_bucket, and update_bucket (rename). Bucket reads run automatically; writes follow the agent’s approval flow. For a hosted app or page, its default is create_site, which creates a bucket automatically. It can attach an existing unattached bucket with create_site.bucket_id. Its file-editing tools remain site-oriented.

The interfold CLI is the primary interface for local coding agents. It stores credentials, resolves site context, and detects content types. Agents with a remote MCP client can instead connect to the Interfold MCP server using an API key. Prefer these interfaces over raw REST API calls unless the task needs an operation they do not expose.

Install the skill so your agent has the full operating guide locally:

interfold skills install

Start CLI tasks with readiness checks

interfold whoami          # confirm authentication
interfold config get      # see defaultAccountId
interfold link status     # see the nearest local account/site binding

If authentication is missing or expired, keep the current agent task alive while the user approves a browser login:

  1. Run interfold login yourself in the current agent terminal.
  2. Tell the user to sign in and approve Interfold CLI in the browser. Leave the command running.
  3. Wait for the command to finish, verify with interfold auth status, and continue the original website task.

If the agent runtime cannot keep a terminal process alive, ask the user to run interfold login and re-check authentication when they return. Never ask the user to paste an API key or share a credential file, and never write credentials into project files — the CLI owns credential storage.

If your agent paused during login

Paste this into the same agent conversation after approving the browser login:

I approved Interfold login. Please re-check `interfold auth status` and continue the website task from where you left off. Do not ask me to log in again or paste credentials.

Choose a site deliberately

Select a site before every site-scoped command. Reuse an existing active site for updates or standalone pages; create a new site only for a genuinely new project or an explicit request.

interfold sites list --status ACTIVE --limit 50
interfold sites get <site-id>       # read the real subdomain before building URLs

When reusing a site, preserve /web/index.html unless the user clearly wants the homepage replaced. For a new standalone page, use a workspace path like /web/demo.html, hosted at /demo.html.

For MCP, call list_sites and get_site instead. Pass the explicit site ID to each site-scoped tool. MCP write_file changes the live site immediately; it does not stage changes for a later deployment. The site agent can list recent file revisions, read a historical text revision, and restore one with approval. The restore creates a new current revision and requires the current version ID returned by get_site_file or the file list.

Publish, then verify

Never report a page as live without checking the hosted URL.

interfold files put ./index.html /web/index.html --site <site-id> --content-type 'text/html; charset=utf-8'
interfold sites get <site-id>
curl -I https://<subdomain>.interfold.site/index.html
curl -I https://<subdomain>.interfold.site/            # for the homepage, verify root too

If verification fails, report the failed command and the error text. Do not claim success.

Access defaults

  • Site access is PUBLIC or PRIVATE. If the user expects anonymous visitors, the site must be PUBLIC.
  • Site access gates anonymous /web/ files only. Every deployed /api/<name> runtime is anonymously callable; its handler must own any authorization.
  • Bucket and Files APIs, function source, cron source, data, database state, migration assets, and other stored objects remain account-private.

Full model in Sites & access.

Handle secrets safely

  • Set secrets via stdin: printf '%s' "$VALUE" | interfold secrets set NAME --site <id>.
  • Verify existence with secrets list, not secrets get.
  • Never print secret values in summaries or logs.

Report results precisely

After a successful task, state:

  • the site id,
  • the paths you changed,
  • the live URL,
  • the verification you performed.

Keep it short and factual. Don’t mention local credential paths unless a troubleshooting step requires it.

On this page