Context

How sitectl models sites, environments, and the saved connection information for each one.

A context is sitectl’s saved record of how to reach a specific environment for a specific site.

The model

sitectl organizes around three concepts:

• A site is the project itself — for example, museum.
• An environment is where that site runs: local, staging, prod, and so on.
• A context is the saved connection record for a site/environment pair.

A single site typically has multiple contexts:

museum-local    → Docker running on your own machine
museum-staging  → Docker on a remote server, reached over SSH
museum-prod     → Docker on a production server, reached over SSH

Contexts are stored in a file at ~/.sitectl/config.yaml and include everything sitectl needs to connect and operate: the project location, environment files, and for remote environments, the connection details.

Local vs remote

Local contexts connect directly to Docker on your own machine. This is the standard setup for development.

Remote contexts send Docker commands through an encrypted tunnel to a server. From your perspective the commands work identically — sitectl handles the connection transparently. You use the same sitectl compose ps whether the site is running locally or on a production server.

Context autodiscovery

sitectl can infer the active context from your current working directory. If your terminal is inside a project directory that matches a context’s project directory, sitectl uses that context automatically.

The resolution order is:

1. An explicit --context flag on the command
2. A context whose project directory matches the current working directory
3. The current-context set in ~/.sitectl/config.yaml

Managing contexts

The sitectl config subcommands manage your contexts.

1. View all contexts

   sitectl config get-contexts
   
2. Inspect a single context

   sitectl config view museum-prod
   
3. Switch the active context

   sitectl config use-context museum-staging
   
4. Delete a context

   sitectl config delete-context museum-old
   

You can also create contexts interactively through the TUI when you connect to or create a site for the first time.

Targeting a specific context per command

Any sitectl command accepts --context to target a specific environment without changing your current context:

sitectl compose logs --context museum-prod
sitectl drupal drush cron --context museum-staging
sitectl validate --context museum-prod

Context fields

Core fields

Field	Description
name	Unique context identifier
site	Site name this context belongs to
plugin	The sitectl plugin that owns this context (e.g. drupal, isle)
project-dir	Absolute path to the project directory on the host
docker-socket	Path to the Docker socket (the file Docker listens on for commands)
project-name	Human-readable project name
compose-project-name	Value injected as COMPOSE_PROJECT_NAME

Compose fields

Field	Description
compose-file	One or more file paths, injected as -f flags
env-file	One or more environment file paths, injected as --env-file flags
compose-network	Docker network name used to resolve service addresses

Remote (SSH) fields

Field	Description
ssh-hostname	The server address to connect to
ssh-user	Your username on that server
ssh-port	SSH port (default: 22)
ssh-key-path	Path to your SSH private key file

Context names are case-insensitive when looked up by name.