Using Profiles to Manage Multiple Development Contexts

A ConfigSync profile is a named set of configuration that activates based on context. Each profile can carry its own variables (used in templates), environment overrides (applied to .env files during pull), and path associations (directories that trigger auto-activation).

Think of profiles as workspaces. A freelance developer might have profiles for personal, client-acme, and client-globex. Each workspace has different git credentials, API keys, and editor settings. Profiles keep these contexts separated without maintaining multiple machines.

Create a profile with a name, an optional environment tier, and an optional path association:

The --copy-from flag duplicates all variables and env overrides from an existing profile. This is useful when a new context is similar to an existing one and you only need to change a few values.

When ConfigSync needs to determine the active profile, it checks these sources in order, using the first match:

For most developers, path matching (priority 5) handles daily use. The .configsync-profile file is useful for project-level overrides — drop one into a repo root and anyone on the team who clones it gets the right profile. ConfigSync walks up the directory tree looking for this file, so it works from nested subdirectories too.

Variables are key-value pairs attached to a profile. They are available in templates as {{vars.VARIABLE_NAME}}:

Profile variables override machine variables of the same name. This means you can set a default EDITOR at the machine level and override it per profile when needed.

Environment overrides replace values in .env files when pulling. This is how you keep different API keys and database URLs per context:

When you run configsync pull, the active profile's overrides are applied to every .env file being restored. The original values remain in the cloud snapshot — overrides are applied at restore time, not at push time.

You can explicitly switch the active profile at any time:

Switching the active profile sets a persistent default (priority 4 in the resolution order). However, if you are in a directory that matches a different profile's path, the path match takes precedence. This means you rarely need to switch manually — just cd into the right directory and the correct profile activates.

Profiles are part of your ConfigSync state. When you push, your profile definitions, variables, and env overrides are all included. When you pull on a new machine, every profile is restored with its full configuration.

This means setting up a new machine with multiple contexts is a single command. Create your profiles once, push them, and every future machine starts with the same clean separation between work, personal, and client projects.