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
    ├── resolved-mcps.json      # MCP servers the last unpack resolved
    ├── installed-mcps.json     # MCP entries unpack wrote into harness config
    ├── link.json               # LEGACY — read once for migration, never written
    ├── orchestration-link.json # set when the folder is linked to an orchestration
    ├── orchestration-sync-state.json # orchestration drift baseline
    └── .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`.
`resolved-mcps.json`	Every MCP server the last `agent unpack` resolved — the agent's own and the built-ins — as a JSON array. `mcp check` reads it to find servers when no native harness config was written.
`installed-mcps.json`	The MCP entries `agent unpack` wrote into native harness config, each with the harness, scope and a fingerprint of what was written. A later unpack uses it to tell an entry it wrote from one you replaced under the same name, and to remove only its own.
`orchestration-link.json`	Present when the folder is linked to an orchestration: the orchestration id, its team and organization, and when it was linked. Delete it after `orchestration delete` to recreate the orchestration with `orchestration create`.
`orchestration-sync-state.json`	The orchestration's state at the last pull or push — member revisions, edges, schedule triggers and metadata. `orchestration status` and `orchestration push` compare against it to tell a local edit from a cloud one.

Per-skill: .brainbase.json

skill add, skill update and template installs stamp a .brainbase.json inside each skill folder they write. It records where the skill came from — GitHub, git, the registry or a local path — so skill update can fetch it again and skill list can show its source, and so a later template pack can tell whether to reference the skill or inline it. It sits beside SKILL.md. A skill folder without one is treated as one the CLI did not install, so a template install never displaces it to make room for its own skill.

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.