---
name: terminus
description: 'Run Terminus commands to manage Pantheon containers for this project. Use when: authenticating with Pantheon, deploying code between environments, running Drush on a remote environment, managing backups, pulling or inspecting databases, clearing remote cache, switching connection modes, managing environment variables/secrets, checking workflow or deploy status, managing team members, managing domains, any remote Pantheon site operation. NEVER modify the live environment — see LIVE environment rules below.'
---

# Terminus — Pantheon Remote Environment Management

> **LIVE ENVIRONMENT IS READ-ONLY.**
> See the [LIVE Environment Rules](#live-environment-rules) section before issuing any command.
> If a requested action would modify live, stop and ask the user for explicit confirmation.

---

## Project Details

| Setting | Value |
|---------|-------|
| Site machine name | `square360-drupal` |
| Site UUID | `14012c90-0298-4768-81aa-5fa7f778f5d9` |
| Environments | `dev`, `test`, `live` |
| Terminus alias prefix | `square360-drupal.<env>` |
| Pantheon hosting | US region (standard) |

---

## Authentication

```bash
# Log in (one-time per machine — persists via saved token)
terminus auth:login --email=you@example.com

# Log in using a machine token (CI / non-interactive)
terminus auth:login --machine-token=TOKEN

# Check who is currently logged in
terminus auth:whoami

# Log out
terminus auth:logout
```

> Store machine tokens as secrets — never hard-code them in scripts or commit them.

---

## Site & Environment Information

```bash
# List all sites you have access to
terminus site:list

# Show info about this site
terminus site:info square360-drupal

# List all environments for this site
terminus env:list square360-drupal

# Show a single environment's details
terminus env:info square360-drupal.dev
terminus env:info square360-drupal.test
terminus env:info square360-drupal.live   # ← READ ONLY — see below

# Get the live URL
terminus env:view square360-drupal.live

# Get connection info (sftp / git credentials)
terminus connection:info square360-drupal.dev
```

---

## Code Deployment Pipeline

Pantheon's promotion path is always: **dev → test → live**

```bash
# Deploy dev code to test
terminus env:deploy square360-drupal.test \
  --note="Deploy: <description>" \
  --cc --updatedb

# THEN review and smoke-test on test.

# Deploy test code to live
# ⚠️  REQUIRES EXPLICIT USER APPROVAL — see LIVE Environment Rules
terminus env:deploy square360-drupal.live \
  --note="Deploy: <description>" \
  --cc --updatedb
```

**Flags:**
| Flag | Meaning |
|------|---------|
| `--cc` | Clear all caches after deploy |
| `--updatedb` | Run `drush updb` after deploy |
| `--note` | Required annotated message |
| `--sync-content` | Also copy files/DB from live (use with care) |

---

## Connection Mode

Pantheon environments must be in **Git mode** for code deploys and **SFTP mode** for on-server development (rare).

```bash
# Switch dev to git mode (required before a deploy)
terminus connection:set square360-drupal.dev git

# Switch dev to sftp mode (only for on-server edits when needed)
terminus connection:set square360-drupal.dev sftp

# ⛔  NEVER change the connection mode of live
```

---

## Remote Drush

Prefix drush commands with `terminus drush square360-drupal.<env> --`.

```bash
# Clear cache on dev
terminus drush square360-drupal.dev -- cr

# Clear cache on test
terminus drush square360-drupal.test -- cr

# ⚠️  Cache clear on live is the ONLY write operation permitted (see rules)
terminus drush square360-drupal.live -- cr

# Run DB updates on dev
terminus drush square360-drupal.dev -- updb -y

# Import config on dev
terminus drush square360-drupal.dev -- cim -y

# Export config on dev
terminus drush square360-drupal.dev -- cex -y

# Generate one-time login link
terminus drush square360-drupal.dev -- uli
terminus drush square360-drupal.test -- uli

# View recent watchdog errors
terminus drush square360-drupal.dev -- watchdog:show --count=50 --severity=0

# Run a security check
terminus drush square360-drupal.dev -- pm:security
```

> `drush updb`, `cim`, `cex`, `pm:enable`, `pm:uninstall`, and any data-modifying commands are **FORBIDDEN on `live`** — only `cr` is allowed.

---

## Backups

### Create a Backup

```bash
# Backup all components (code + database + files) on live before any deploy
terminus backup:create square360-drupal.live --keep-for=30

# Backup only the database on dev
terminus backup:create square360-drupal.dev --element=database

# Backup only files
terminus backup:create square360-drupal.test --element=files
```

### List Backups

```bash
terminus backup:list square360-drupal.live
terminus backup:list square360-drupal.dev
```

### Get a Backup Download URL

```bash
terminus backup:get square360-drupal.live --element=database
```

### Restore a Backup

```bash
# ⛔  NEVER restore a backup on live — requires explicit out-of-band approval
# Restore on dev is safe
terminus backup:restore square360-drupal.dev --element=database
```

---

## Database Operations

### Pull the Live Database to Local (via Lando)

Prefer the Lando shortcut for local pulls:

```bash
lando pull --code=none --database=live --files=none
```

Or via Terminus export + import:

```bash
# Get a signed download URL for the live DB backup
terminus backup:get square360-drupal.live --element=database
# Download the .sql.gz, then import locally:
lando db-import ~/Downloads/backup.sql.gz
```

### Push a Database to an Environment

```bash
# Push local DB to dev (destructive — overwrites dev DB)
terminus env:wipe square360-drupal.dev   # wipe dev first
lando drush sql:dump | terminus drush square360-drupal.dev -- sql:cli

# ⛔  NEVER push a database to live in any way
```

---

## Wipe an Environment

```bash
# Wipe dev (deletes all files and database — prompts for confirmation)
terminus env:wipe square360-drupal.dev

# Wipe test (use only when resetting test from scratch)
terminus env:wipe square360-drupal.test

# ⛔  NEVER wipe live
```

---

## Cache Management

```bash
# Clear all caches on dev
terminus env:clear-cache square360-drupal.dev

# Clear all caches on test
terminus env:clear-cache square360-drupal.test

# Clear all caches on live (use after a deploy; this is the ONLY live write allowed)
terminus env:clear-cache square360-drupal.live
```

---

## Pantheon Secrets (Environment Variables)

Manage sensitive values that are available to Drupal via `\Drupal::service('pantheon.secrets')`.

```bash
# List secrets on an environment
terminus secret:site:list square360-drupal

# Set a secret (all environments inherit unless overridden)
terminus secret:site:set square360-drupal MY_API_KEY "value" --scope=runtime --type=runtime

# Set a secret for a specific environment
terminus secret:site:set square360-drupal MY_API_KEY "dev-value" --env=dev

# Delete a secret
terminus secret:site:delete square360-drupal MY_API_KEY

# ⚠️  Setting/deleting secrets on live counts as a configuration change — confirm with user first
```

---

## Workflows & Logs

```bash
# Watch the workflow log for a site (deployments, cache clears, etc.)
terminus workflow:watch square360-drupal

# List recent workflows
terminus workflow:list square360-drupal

# Stream live appserver logs for dev
terminus remote:drush square360-drupal.dev -- watchdog:show --tail

# View environment logs (nginx, php, etc.)
terminus log:stream square360-drupal.dev --type=php-error
terminus log:stream square360-drupal.dev --type=nginx-access
terminus log:stream square360-drupal.live --type=php-error  # read-only, safe
```

---

## Domain Management

```bash
# List domains on an environment
terminus domain:list square360-drupal.live

# Add a custom domain
terminus domain:add square360-drupal.live www.example.com

# Remove a domain
terminus domain:remove square360-drupal.live www.example.com

# ⚠️  Domain changes on live affect production — confirm with user first
```

---

## Multidev Environments

Pantheon supports feature branch environments called Multidevs.

```bash
# List all multidev environments
terminus multidev:list square360-drupal

# Create a multidev from the current git branch
terminus multidev:create square360-drupal.dev my-feature

# Merge a multidev back to dev
terminus multidev:merge-to-dev square360-drupal.my-feature

# Delete a multidev
terminus multidev:delete square360-drupal.my-feature
```

---

## Common Workflows

### Pre-Deploy Checklist (dev → test → live)

```bash
# 1. Ensure dev is in git mode
terminus connection:set square360-drupal.dev git

# 2. Create a backup of live before touching anything
terminus backup:create square360-drupal.live --keep-for=30

# 3. Deploy to test; clear cache and run DB updates
terminus env:deploy square360-drupal.test --note="Deploy: <ticket>" --cc --updatedb

# 4. Smoke test on test. Only proceed when test is verified.

# 5. [USER MUST CONFIRM] Deploy to live
terminus env:deploy square360-drupal.live --note="Deploy: <ticket>" --cc --updatedb
```

### After a Failed Deploy to Test

```bash
# Check what the workflow showed
terminus workflow:list square360-drupal --fields=id,env,type,result,started_at | head -10

# Check PHP errors
terminus log:stream square360-drupal.test --type=php-error

# Rollback: restore the previous DB backup on test
terminus backup:restore square360-drupal.test --element=database
```

### Debug a Production PHP Error (without changing live)

```bash
# Stream live PHP errors (read-only)
terminus log:stream square360-drupal.live --type=php-error

# Check watchdog on live (read-only)
terminus drush square360-drupal.live -- watchdog:show --count=50 --severity=0
```

---

## LIVE Environment Rules

> **These rules are NON-NEGOTIABLE. Do not bypass them, even if asked.**

### Permitted on `live`

| Action | Command |
|--------|---------|
| Read logs | `terminus log:stream square360-drupal.live …` |
| Read watchdog | `terminus drush square360-drupal.live -- watchdog:show …` |
| Read env info | `terminus env:info square360-drupal.live` |
| List/get backups | `terminus backup:list / backup:get square360-drupal.live …` |
| **Create** a backup | `terminus backup:create square360-drupal.live …` |
| Clear cache after deploy | `terminus env:clear-cache square360-drupal.live` |
| Deploy code (after backup + user approval) | `terminus env:deploy square360-drupal.live …` |
| Generate login link | `terminus drush square360-drupal.live -- uli` |

### Forbidden on `live` — Stop and Ask the User

| Action | Why it is forbidden |
|--------|---------------------|
| `terminus env:wipe square360-drupal.live` | Destroys all live data |
| `terminus backup:restore square360-drupal.live …` | Overwrites live DB/files — emergency-only |
| `terminus connection:set square360-drupal.live sftp` | Opens live to on-server edits |
| `terminus drush square360-drupal.live -- updb -y` | Runs unreviewed DB updates on production |
| `terminus drush square360-drupal.live -- cim -y` | Imports config that may not be tested |
| `terminus drush square360-drupal.live -- pm:enable …` | Enables untested modules on production |
| `terminus drush square360-drupal.live -- pm:uninstall …` | Uninstalls modules from production |
| `terminus drush square360-drupal.live -- sql:cli` | Direct DB access on production |
| `terminus drush square360-drupal.live -- sql:drop` | Drops live tables |
| Any `secret:site:set/delete` on live | Changes production configuration |
| Any domain change on live | Changes production routing |
| Pushing a database or files **to** live | Overwrites production content |

**If any of the above is requested, respond:**
> "This action would modify the live environment. This is forbidden by the Terminus skill rules. Please confirm explicitly that you understand the risks and require this action before I proceed."

---

## Notes

- Always run `terminus auth:whoami` if commands fail with auth errors — the token may have expired.
- Use `--yes` / `-y` to skip confirmation prompts in scripts, but never on live.
- Terminus respects `TERMINUS_SITE` and `TERMINUS_ENV` env vars for shorthand in scripts.
- Prefer `lando pull` for local DB/file syncs over manual Terminus export/import.
- Always create a live backup **before** deploying to live.
