# For AI agents

heremyapp is built to be used by coding agents (Claude Code, Codex, Cursor and others) with nothing more than a shell:
`curl`, `tar` and `shasum`. No SDK or plugin is required.

## For people: what to tell your agent

Give the agent a token first (see [Authentication](https://heremyapp.com/docs/authentication.md)), then ask in plain words, for example:

```text
Deploy this project's landing page to heremyapp. Read https://heremyapp.com/llms.txt first.
```

```text
Build MyApp.pkg, publish it on heremyapp as the app's current version, and point the landing page's
download button at it. Read https://heremyapp.com/docs/installers.md and https://heremyapp.com/docs/sites.md first.
```

Every docs page has a "Copy Markdown" button, so you can also paste a page straight into the conversation.

## Agent skill

Agents that support skills (for example Claude Code) can install the heremyapp skill:

```bash
mkdir -p ~/.claude/skills/heremyapp && curl -fsSL https://heremyapp.com/skill.md -o ~/.claude/skills/heremyapp/SKILL.md
```

## Machine-readable discovery

| URL | What it is |
|---|---|
| `https://heremyapp.com/llms.txt` | Index of these docs ([llms.txt](https://llmstxt.org/)) |
| Any docs page with `Accept: text/markdown` | The page as Markdown, same as adding `.md` |
| `https://heremyapp.com/openapi.json` | OpenAPI 3.1 description of the API |
| `https://heremyapp.com/.well-known/api-catalog` | API catalog (RFC 9727) pointing to the API, its spec and docs |
| `https://heremyapp.com/.well-known/agent-skills/index.json` | Agent Skills index with the heremyapp skill |
| `https://heremyapp.com/.well-known/auth.md` | How agents authenticate |

Pages also send `Link` headers to these resources.

## Recommended workflow

1. Resolve the token (`HEREMYAPP_TOKEN`, then `~/.config/heremyapp/token`, else ask the user) and call `GET /me`.
   Note `account.username`. If the token scope is `space`, use the space from `GET /spaces`.
2. Create the space, or reuse it on `409 space_exists`.
3. Check versions: `GET /spaces/SPACE/versions` ([Releases and versioning](https://heremyapp.com/docs/releases.md)). Decide the bump from what
   changed, without asking the user.
4. Contact details: if `contact_status` is `unknown`, ask the user once (skipping is fine) and save the answer
   ([Landing page checklist](https://heremyapp.com/docs/landing.md)).
5. If there is an installer: set the next version and build in the project, build, check its signature (macOS:
   `spctl`; ask the user if it fails), then publish it with `version`, `build` and `notes`
   ([Installers](https://heremyapp.com/docs/installers.md)). The latest link is `https://heremyapp.com/dl/ACCOUNT/SPACE/latest/FILENAME`.
6. Prepare the site with the [Landing page checklist](https://heremyapp.com/docs/landing.md): content, often-missed items, languages, contact
   details, and the app's version, size and release notes. If a landing page exists, update it instead of replacing it.
   A new site gets `/privacy` and `/terms` from the templates, linked from every page ([Privacy policy and terms](https://heremyapp.com/docs/legal.md)).
7. Deploy the site with `bump` and `notes` ([Static sites](https://heremyapp.com/docs/sites.md)). Read the response's `advice` list, fix what
   applies, and deploy again if needed.
8. Verify: the public URL returns 302 then 200 with the new `X-Heremyapp-Version`, and the downloaded installer's
   SHA-256 matches the local file.
9. Report the public URL (`https://heremyapp.com/ACCOUNT/SPACE`), the download link, and the new versions and build numbers.

## Rules

- Never print, log or commit the token, and never put it into site files.
- Do not create accounts or guess tokens. If there is no token, ask the user.
- Share the public URL, not the site origin it redirects to.
- When a request fails, read `error.message`: it says what to change. `error.docs` links back to these docs.
- Do not upload an installer that fails signature checks unless the user explicitly says so.
- Manage versions and build numbers yourself on every deploy; do not ask the user to choose them.
- Ask for contact details at most once per space; respect `skipped`.

## Troubleshooting

| Symptom | What to do |
|---|---|
| `Could not resolve host` for a heremyapp host | Usually a stale local DNS cache. Resolve it directly and pin it: `IP=$(dig +short api.heremyapp.com @1.1.1.1 \| head -1)`, then add `--resolve api.heremyapp.com:443:$IP` to curl. The user can clear the cache on macOS with `sudo killall -HUP mDNSResponder`. |
| `401 unauthorized` | The token is missing, mistyped, expired or revoked. Ask the user for a valid token. |
| `403 forbidden` | A space token was used for another space or for an account-only action. |
| `unsupported_file_type` | Remove the files listed in `details.files` from the site folder, or publish installers as artifacts. |
| `409 artifact_exists` | That version is already published. Use a new version. |