> ## Documentation Index
> Fetch the complete documentation index at: https://libops-renovate-github-com-libops-sitectl-isle-0-x.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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

export const SSH = () => <Tooltip headline="SSH" tip="Secure Shell (SSH) is an encrypted protocol for connecting to and controlling a remote computer over a network. sitectl uses SSH to reach Docker on remote servers.">
    SSH
  </Tooltip>;

export const TUI = () => <Tooltip headline="TUI" tip="Terminal User Interface: an interactive command-line interface for navigating and operating sitectl.">
    TUI
  </Tooltip>;

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

## First launch

After [installing sitectl](/install), run:

```bash theme={null}
sitectl
```

This opens the interactive <TUI /> — 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 <TUI /> 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 <TUI /> setup flow, or with `sitectl config set-context` directly. See [Contexts](/context) for the full model.

Once you have a context, sitectl knows:

* Where the <Compose /> project files live
* Whether to connect locally or over <SSH />
* Which plugin owns this site (Drupal, ISLE, etc.)

## Core workflow

The core workflow commands form a natural progression:

<Steps>
  <Step title="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.

    ```bash theme={null}
    sitectl validate
    ```

    Exits with an error if anything is wrong. Safe to run any time.
  </Step>

  <Step title="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.

    ```bash theme={null}
    sitectl set fcrepo off
    sitectl set iiif triplet
    ```

    Shared ingress settings such as TLS mode and bot mitigation use [Traefik service commands](/plugins/traefik).
  </Step>

  <Step title="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.

    ```bash theme={null}
    sitectl converge --report   # preview
    sitectl converge            # apply
    ```
  </Step>

  <Step title="Deploy — pull updates and restart">
    Use `sitectl deploy` to apply an upstream update: pull the latest code, update container images, and restart services.

    ```bash theme={null}
    sitectl deploy
    sitectl deploy --branch main
    ```
  </Step>

  <Step title="Healthcheck — confirm the app is running">
    Run `sitectl healthcheck` for a basic status check of the running application.

    ```bash theme={null}
    sitectl healthcheck
    sitectl healthcheck --format table
    ```
  </Step>

  <Step title="Verify — prove site behavior">
    Use `sitectl verify` after updates to run healthcheck-style status plus additional checks supplied by the active plugin. Wire this into CI to make sure important site functionality remains intact.

    ```bash theme={null}
    sitectl verify
    sitectl verify --format table
    ```
  </Step>
</Steps>

## Day-to-day operations

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

```bash theme={null}
# 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:

```bash theme={null}
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 <TUI /> 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.