# Configuration Directory Squirro CLI keeps everything it manages in a single configuration directory that you hold in version control. The layout mirrors the platform: server-level configuration sits at the top, and each project the directory manages gets its own subdirectory below it. Before starting, make sure Squirro CLI is installed. For more information, see the [Installation](installation.md#squirro-cli-installation) page. ## Terminology The word _project_ has several meanings here, so this documentation uses three distinct names: - **Configuration directory** The version-controlled directory that `squirro init` creates. It holds the configuration of the Squirro projects you manage, together with the profiles for the instances you apply that configuration to. - **Squirro project** A project on a Squirro instance. - **Project directory** One subdirectory of `projects/`, holding the configuration of a single Squirro project. A fourth term comes up throughout this page: - **Connection profile** One instance you apply the configuration to, usually one per environment. A profile carries the cluster URL, the credentials, and the mapping from each project directory to the identifier of the Squirro project it corresponds to on that instance. For more information, see the [Main Commands](commands.md#squirro-cli-commands) page. ## Create the Configuration Directory A configuration directory covers one set of Squirro projects and the instances you apply them to, so create a separate one for every set you manage. They are independent, each carrying its own profiles and its own project directories. Commands act on the directory you run them from, and `squirro profile create` looks for project directories relative to it, so decide where these live before you create the first one. Keeping them alongside your other repositories works well, and you change into the right one before starting work. `squirro init` runs an interactive wizard that creates the directory layout, optionally writes a connection profile, and offers to pull the current instance configuration straight away. Where you run it depends on whether a delivery repository already exists. ```bash mkdir insights-config && cd insights-config # A new, empty directory squirro init ``` ```bash cd insights-delivery # The root of an existing delivery repository squirro init cli ``` The second form places the configuration directory in a `cli/` subdirectory, which is the convention, and leaves the surrounding repository untouched. Before the wizard starts, `init` looks for a git repository at or above the current directory. Finding none, it offers three choices: add the configuration directory to an existing repository, create a repository where you are, or skip git setup, which is the default. The first example above takes that path, because a new empty directory belongs to no repository. The wizard confirms that you want to continue, then asks, in order: 1. Whether to set up GenAI Platform support. The default is yes. 2. Whether to set up Graphite support. The default is no. 3. Whether to create a connection profile. The default is no. Answering yes leads to the profile name, then the cluster URL and authentication token for GenAI, and the username and password for Graphite. 4. Whether to register projects. The default is yes. For each one, give a project directory name, and then the identifier of the Squirro project it maps to. Registration continues until you answer no to `Add another project?`, which is the default. 5. Whether to pull the configuration from the instance after setup. The default is yes. The wizard asks this only when both a profile and at least one project were configured. > **Note** > > Squirro CLI still refers to Graphite by its former name, Synaptica. The wizard asks about Synaptica platform support, and a connection profile stores the platform under the key `synaptica`, so expect that name in the prompts and in the profile files. > **Tip** > > Have the Squirro project identifiers ready before you start. The wizard prompts for them and offers no interactive picker. The profile that `init` creates is the one you author configuration on. Add the remaining environments afterward with `squirro profile create`, which is also the only command that asks whether a profile is a mirror. For more information, see the [Mirror Profiles](mirror-profiles.md#squirro-cli-mirror-profiles) page. `squirro init --force` reruns the wizard over a directory that already has a `.squirro/`. It does not overwrite anything: existing profiles, configuration, `CLAUDE.md`, skills and project directories are all kept. > **Warning** > > Rerunning with `--force` and answering yes to the profile question leaves the directory unusable. The wizard records the profile name you typed as the default, then declines to create that profile because profiles already exist, so every later command reports that no default profile is configured. Recover by pointing `default_profile` in `.squirro/config.json` at a profile that exists. To add an environment, use `squirro profile create` instead. ## Directory Layout The example below shows how a configuration directory is arranged once the wizard has finished and the first pull has completed. Each directory is created only when you configure or pull the component it holds, so if you do not use a knowledge graph, there is no `taxonomy-ontology/` directory at all. ```text insights-config/ ├── .gitignore ├── CLAUDE.md ├── README.md ├── .claude/ # Assistant skills and tool definitions ├── .squirro/ │ ├── config.json # Default profile and schema version │ ├── profiles/ # Connection profiles │ ├── credentials/ # Stored credentials, never committed │ └── cache/ # Read-only platform-managed assets ├── genai/ # Server-level configuration │ ├── config-server.json │ ├── groups.json │ ├── users.json │ ├── connectors/plugins/ # Local data loader plugins │ ├── genai_plugins/ │ ├── project_templates/ │ ├── studio_plugins/ │ └── widgets/ # Legacy custom widgets └── projects/ # Project-level configuration └── market_intelligence/ ├── platform/ │ ├── info.json │ ├── members.json │ ├── config-project.json │ ├── support.json │ └── theme.json ├── connectors/ │ ├── labels.json │ └── sources/ ├── enrichments/ │ └── workflows.json ├── agents/ ├── dashboards/ └── taxonomy-ontology/ # Graphite templates and schemes ``` For the authoritative list of the files Squirro CLI supports, together with the path of each, run the following command from inside the configuration directory. ```bash squirro config list ``` ### Server-Level Configuration The `genai/` directory holds what is shared across every project on the instance: the server configuration service settings, groups, users, local data loader plugins, GenAI plugins, Studio plugins, project templates, and legacy custom widgets. Platform-managed global data loader plugins are a read-only view. They are cached under `.squirro/cache/` for reference and are never applied back to the instance. ### Project-Level Configuration Each directory under `projects/` maps to one Squirro project, and the mapping from the directory name to the project identifier lives in the connection profile, not in the tracked files. Keeping the identifiers in the profile is what lets the same files apply to a development, staging, and production instance. The directory name is yours to choose, and it does not have to match the name the project shows in the web interface. Only the identifier ties the two together, so pick something short and readable and keep it lowercase, with underscores between words. The `squirro init` wizard replaces every other character with an underscore, so `Market Intelligence` and `market-intelligence` both become `market_intelligence`, and it reports the name it settled on. To use a name the wizard would rewrite, such as one containing dashes, create the directory with `squirro project create` instead. The name shown in the interface is a separate, pulled value, held as the `title` field of `platform/info.json`. Renaming a project in the interface therefore changes that file on the next pull and leaves the directory name untouched. A project directory holds the project metadata, members, project configuration service settings, support contacts, and theme under `platform/`, its labels and data sources under `connectors/`, its pipeline workflows under `enrichments/`, its agents and dashboards in their own directories, and its Graphite content under `taxonomy-ontology/`. > **Note** > > Graphite schemes and templates are pull-only. Editing one produces a report that the change cannot be applied and stays on disk, and `squirro config pull` restores the instance version. Graphite concepts are applied normally. ## Assistant Assets Alongside the configuration, `squirro init` writes the files that let an AI coding assistant work in the directory without further setup: a `CLAUDE.md` file describing the layout and the conventions, and a `.claude/` directory holding skills for common Squirro tasks and tool definitions for reaching the instance. Start your assistant from the configuration directory so that it picks those up. The bundled set depends on the build, so read `.claude/skills/` for what your build ships. When you move to a newer build, refresh those assets and run any pending schema migrations. ```bash squirro init --update ``` That leaves your profiles, your configuration, and `README.md` alone, and keeps any skills and tools you added yourself. Review the result with `git diff` before committing. ## Secrets and What to Commit Tracked configuration files never hold credentials. A sensitive field carries the `…` placeholder token instead, and the real value goes in a sibling `.local.json` file. ```text .squirro/profiles/ ├── dev.json # Tracked, carries the placeholder token ├── dev.local.json # Ignored by git, carries the real token ├── prod.json └── prod.local.json ``` A configuration file refers to a value stored with `squirro secret set-secret` as `${secrets.}`. A value can also be given as an `op://vault/item/field` 1Password reference or as an environment variable, both resolved when the command runs. > **Warning** > > Never give a password, token, or any other credential to an AI assistant. Everything in an assistant session, including anything you paste into a prompt and any command the assistant runs on your behalf, is sent to the model provider. A credential that reaches it has to be treated as compromised and rotated. For the same reason, do not ask an assistant to run `squirro secret set-secret` with a real value, because the value travels with the command. > > > > Put real values in place yourself, outside the assistant, in one of these ways: > > > > - Edit the `.local.json` file in your own editor. > - Run `squirro secret set-secret` yourself, in your own terminal. > - Reference the credential as an `op://vault/item/field` 1Password entry or an environment variable, so that the value never lands in a file at all. > > > > An assistant can still create and edit the tracked configuration files, because those carry only the `…` placeholder and never a real credential. `squirro init` writes a `.gitignore` covering everything that must stay out of version control, and merges those entries into an existing `.gitignore` rather than replacing it: - `*.local.json` and `.squirro/credentials/`, which hold credentials. - `backups/`, the instance state snapshots that `config apply` writes. - `genai/enrichments/kee/*/db/`, compiled lookup databases that are rebuilt rather than tracked. - `.squirro/cache/`, the read-only platform-managed assets. - `.claude/worktrees/`, which git would otherwise stage as a pointer to an unmerged branch. Everything else is meant to be committed, including `.squirro/config.json`, the tracked profiles, the whole of `genai/` and `projects/`, and the assistant assets. > **Important** > > Check your `.gitignore` before the first commit. Builds earlier than `0.2026.09.08.68` write a shorter list and overwrite an existing `.gitignore` instead of merging into it, so a directory created with an older build may be missing the entries above. > **Note** > > Profiles are local to the configuration directory by default, so `squirro init` writes them to `.squirro/profiles/` inside it rather than to `~/.squirro/`. Everyone working in that directory then sees the same set of environments. To create a profile that is visible from any directory, pass `--user` to `squirro profile create`. > > > > A profile created that way keeps its credentials in your home directory, outside any repository, so the `.gitignore` above does not cover it. Nothing can commit it by accident, and equally nothing is protecting it, so it stays yours alone to look after and your team never sees it. ## Tracking Changes and Rolling Back Holding the configuration in version control is what turns a change on a Squirro instance into something you can review, attribute, and undo. Each commit records the intended state of the instance, so the history answers what changed, when, and why, and a change can go through a pull request before it reaches anything live. > **Important** > > Git tracks the files, not the instance. Reverting a commit changes your local configuration and nothing else. The instance keeps the old behavior until you apply the reverted files. To undo a change that is already deployed: 1. Revert the commit, or edit the files back by hand. 2. Run `squirro config apply --dry-run` and read the difference. It compares the reverted files against the live instance, so it shows exactly what the rollback does. 3. Run `squirro config apply`. > **Warning** > > Reverting a commit that added something does not remove it from the instance. Deletion is turned off unless you pass `--allow-deletion`, so the apply instead lists everything it would have deleted, such as a data source or a pipeline workflow, and then warns how many deletions it skipped. Read that list before acting on it, because a deletion cannot be undone by another apply. Where it names resources that should stay, run `squirro config pull` to bring them into your files rather than passing the flag. ### Recovering Prior Instance State Version control holds what you intended. For what the instance actually held, `squirro config apply` writes a snapshot into a timestamped directory before it changes anything. The snapshot covers the configuration the apply is about to touch, not the whole instance, and `config pull` writes none at all. ```text backups/ └── 20260908T151409Z/ ``` Those snapshots are useful when the instance had drifted from the tracked files, so reverting a commit would not restore what was really there. No command reads them back, so use them by reading the values and copying what you need into the tracked files, then applying as above. The directory is git-ignored, which means it is local to the machine that ran the apply and is not shared with your team. Treat it as a short-term safety net rather than as a record, and rely on the commit history for anything you need to keep. ## Next Steps With the configuration directory in place, work through the pull and apply cycle. For more information, see the [Main Commands](commands.md#squirro-cli-commands) page.