# Mirror Profiles A mirror profile is a connection profile for an environment you only push configuration to, such as staging or production. You author configuration against one profile, usually the development one, and replicate it outward. The tracked files stay the single source of truth for every environment. Before starting, make sure you have a configuration directory with at least one profile. For more information, see the [Configuration Directory](configuration-directory.md#squirro-cli-configuration-directory) page. ## The Problem Mirrors Solve The goal is that the configuration in version control is identical for every environment. Promoting a change then becomes a low-risk operation: you switch profile and apply the same files. Anything that must differ between environments belongs in the profile, which carries the cluster URL, the credentials, and the mapping from project directory to project identifier. Treat divergence in the tracked files as a warning sign. Two things get in the way of that goal: - **Record identifiers differ between instances** A pull records the identifier of each workflow and source it downloads. Those identifiers exist only on the instance they came from, so an apply that matches on them finds nothing on a second instance and creates duplicates instead of updating what is there. - **A pull against the wrong environment overwrites the shared files** Every profile shares one set of tracked files. Pulling while a staging or production profile is active replaces those files with that one environment’s state, which is the opposite of what promotion needs. Marking a profile as a mirror addresses both. ## What the Mirror Flag Changes - **Apply matches records by name** `config apply` and `config validate` match by name rather than by identifier, which is the same behavior as passing `--apply-by-name`. Each run reports which profile it is treating as a mirror, so you can confirm from the output that the profile is set up as intended. Where two records on the target share a name, the run reports an error rather than guessing. - **Pull asks for confirmation first** `config pull` warns that pulling on a mirror overwrites the shared files with that environment’s data, and waits for confirmation. The pull is not blocked, so pass `--yes` for a non-interactive run. An explicit `--apply-by-name` or `--no-apply-by-name` on the command line overrides the profile flag either way. Everything else behaves the same. Deletions stay off unless you pass `--allow-deletion`, and an apply still shows the difference and asks for confirmation. ## Mark a Profile as a Mirror `squirro profile create` is the only command that asks the mirror question. The `squirro init` wizard does not, so the profile it creates is never a mirror, which is correct: that is the one you author on. Create the mirror profiles for your other environments afterward. ```bash squirro profile create prod ``` The command explains what a mirror profile is, then asks `Is this an apply-only (mirror) profile?`. Answer no for the profile you author configuration on, and yes for every environment you replicate to. > **Note** > > The question defaults to yes as soon as one profile already exists in that scope, on the assumption that the first profile you create is the one you author on and every later one is a mirror. It is only a default, so answer no where that does not hold. The command then works through the project directories it finds under `projects/`, asking for each whether to connect it to a project on that instance and, if so, for the project identifier. An empty identifier leaves that directory unconnected and the command moves on to the next one. When nothing ends up connected, it offers to name one more directory, defaulting to the profile name, before reporting that no project is connected. Add a mapping later with `squirro project create`. The profile list marks which profiles are mirrors. ```bash squirro profile list ``` The flag is stored as `"mirror": true` in the profile JSON file. No command changes it after creation, so to convert an existing profile, edit `.squirro/profiles/.json`, or `~/.squirro/profiles/.json` for a user-scoped profile. ## The Promotion Workflow Author on the primary profile, then replicate outward without pulling. 1. Run `squirro --profile dev config pull` to start from the state of the development instance. 2. Edit the tracked files. 3. Run `squirro --profile dev config apply` to push the change to development. 4. Run `squirro --profile staging config apply` to replicate it outward, with no pull in between. 5. Run `squirro --profile prod config apply` to replicate it to production. Preview any of those with `config apply --dry-run`, or with `config validate`, which resolves record matching from the profile the same way and therefore previews the apply it is describing. > **Important** > > Never run `config pull` against a mirror profile as part of this loop. The pull would replace the tracked files with that environment’s state and lose the configuration you are promoting. That is what the confirmation prompt exists to catch. ## Setting Up a New Environment To bring a new instance under the same configuration: 1. Create a profile for it with `squirro profile create`, answering yes to the mirror question. 2. Connect each project directory to a project on that instance when the command asks, or register them later with `squirro project create --profile `. 3. Run `squirro --profile connection` to confirm the credentials work. 4. Preview with `squirro --profile config apply --dry-run`, then apply. The new environment then matches the tracked configuration, and later changes reach it with a single apply. ## Next Steps For the full set of configuration commands and their options, see the [Main Commands](commands.md#squirro-cli-commands) page.