# 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](https://llmstxt.org) convention:

- **[/llms.txt](/llms.txt)** — an index of every doc with one-line descriptions
  and links. Fetch this first to orient.
- **[/llms-full.txt](/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:

```sh
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](/mcp) using
an API key. Prefer these interfaces over raw [REST API](/api-reference) calls
unless the task needs an operation they do not expose.

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

```sh
interfold skills install
```

## Start CLI tasks with readiness checks

```sh
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:

```text
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.

```sh
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.

```sh
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](/sites).

## 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.

---

Deeper references: [CLI](/cli) · [MCP](/mcp) · [API](/api-reference) · [Functions](/functions) ·
[Cron Jobs](/cron-jobs) · [Databases](/databases) · [Data files](/data-storage) ·
[Secrets](/secrets)

Hosted `/web/` files follow Site-wide access. Per-file access overrides are not
supported; function handlers own their authorization.