Quickstart

Get sitectl running and understand the core workflow in a few minutes.

First launch

After installing sitectl, run:

sitectl

This opens the interactive — a live dashboard showing your sites and their current state. From here you can connect to an existing site or create a new one.

If you prefer to stay in the command line without the dashboard, every operation in the also has a direct command equivalent.

Setting up a site

The first thing sitectl needs is a context — a saved record of how to connect to a site and which environment you’re working with (local, staging, production, etc.).

You can create one through the setup flow, or with sitectl config set-context directly. See Contexts for the full model.

Once you have a context, sitectl knows:

• Where the project files live
• Whether to connect locally or over
• Which plugin owns this site (Drupal, ISLE, etc.)

Core workflow

The four commands you’ll use most often form a natural progression:

1. Validate — check before you act

   Run sitectl validate to confirm the site configuration is consistent before making changes. It checks that the project files are present, the context is wired correctly, and that no components have drifted.

   sitectl validate
   

   Exits with an error if anything is wrong. Safe to run any time.

2. Set — record a configuration choice

   Use sitectl set to turn optional features on or off. This records your intent but does not immediately change project files.

   sitectl set fcrepo off
   sitectl set isle-tls on --tls-mode letsencrypt
   
3. Converge — apply changes

   Use sitectl converge to bring project files into alignment with the current desired state. Run --report first to preview what would change.

   sitectl converge --report   # preview
   sitectl converge            # apply
   
4. Deploy — pull updates and restart

   Use sitectl deploy to apply an upstream update: pull the latest code, update container images, and restart services.

   sitectl deploy
   sitectl deploy --branch main
   

Day-to-day operations

Beyond the core workflow, a few commands come up regularly:

# Run any docker compose command against the active context
sitectl compose ps
sitectl compose logs drupal --tail 50

# Run a Drush command inside the Drupal container
sitectl drupal drush cr

# Collect a diagnostic bundle when something is wrong
sitectl debug

# Forward a remote service port to your local machine
sitectl port-forward

Targeting a specific environment

Every sitectl command accepts --context to target a specific environment without changing your default:

sitectl validate --context museum-prod
sitectl compose logs --context museum-staging
sitectl deploy --context museum-prod

When to use the TUI vs direct commands

The is best for monitoring, setup, and interactive exploration. Direct commands are better for one-off operations, automation, and scripting. Both modes work against the same contexts and share all underlying logic.