Reference

Files & state

The CLI keeps state in two places: a global config directory under your home folder, and a per-folder .brainbase/ directory in each linked agent.

Global: ~/.brainbase/

Override the location with BRAINBASE_HOME.

text

~/.brainbase/
├── auth.json          # signed-in session (mode 0600)
├── token.json         # long-lived CLI PAT (bbpat_…), mode 0600
├── installed.json     # registry of every installed template on this machine
├── registry/          # packed templates available to install
│   └── <creator>/<slug>/<version>/
└── cache/             # transient caches

File	Purpose
`auth.json`	Browser-login session (JWT + user). Mode `0600`.
`token.json`	PAT issued by `token create`. Mode `0600`. Format `bbpat_…`.
`installed.json`	Index of every template install across folders. Used by `template list --all` and `template remove`.
`registry/`	Locally available templates, each a self-contained `<creator>/<slug>/<version>/` bundle.
`cache/`	Transient caches.

Per-folder: <your-folder>/.brainbase/

Created when you link or pull an agent into a folder. Holds cloud-derived content and per-checkout state. An auto-generated .gitignore (containing * and !.gitignore) keeps the entire .brainbase/ directory out of source control — only brainbase.agent.yaml at the folder root is meant to be committed.

text

<linked-folder>/
├── brainbase.agent.yaml   # the committed manifest (source of truth)
└── .brainbase/            # entire directory is gitignored
    ├── state.json              # cached cloud metadata (slug, url, org/team, tracking)
    ├── sync-state.json         # per-checkout drift / hashes
    ├── secrets.env             # agent secrets, .env format
    ├── instructions.md         # pulled instructions body
    ├── playbooks/              # pulled playbook bodies (<slug>.md)
    ├── entrypoint.sh           # resolved entrypoint script (chmod 0755)
    ├── entrypoint.log          # entrypoint run log
    ├── link.json               # LEGACY — read once for migration, never written
    ├── orchestration-link.json # set when the folder is part of an orchestration
    └── .gitignore              # auto-created: `*` + `!.gitignore`

File	Purpose
`state.json`	Cached cloud metadata for the claimed agent (org/team, slug, url, tracking). Not the source of truth — regenerated from the cloud. Together with the manifest's `id`, this is what records which agent the folder is linked to.
`sync-state.json`	Per-checkout last-sync revision + per-component hashes.
`secrets.env`	Agent secrets in `.env` format. Written by `agent pull`; read by `agent push` and `run`. Never commit it.
`instructions.md` / `playbooks/`	Bodies written by `pull`; `unpack` lays them into the harness's expected paths.
`entrypoint.sh` / `entrypoint.log`	The resolved sandbox entrypoint script and its run log.
`link.json`	Legacy. Read once for a one-time migration into `state.json`, then never written. The "which agent is this folder linked to" role now belongs to `state.json` + the manifest's `id`.
`orchestration-link.json`	Present when the folder is a member of an orchestration.

Keep secrets out of git

The whole .brainbase/ directory is gitignored automatically (the generated .brainbase/.gitignore is * + !.gitignore), so secrets.env and everything beside it stays out of source control. Only brainbase.agent.yaml at the folder root is committed. Don't move secret values into that committed manifest — store them as agent secrets instead.