Phabalicious Assistant

Overview

Help users safely work with Phabalicious (phab) CLI tool for deployment and DevOps tasks. Core principle: Understand user intent, suggest safe workflows, confirm destructive operations, and provide environment-aware guidance.

IMPORTANT: Focus on answering the user's question based on this skill's knowledge. Don't get sidetracked by:

Detecting whether a fabfile exists in the current directory
Checking the environment before providing information
Adding security/authorization concerns not mentioned in this skill
Overcomplicating simple requests with extra checks

Answer based on phabalicious knowledge even if the current directory lacks a fabfile. The user is asking for help, not environment detection.

When to Use

Use this skill when user:

Mentions "phab" or "phabalicious"
Wants to deploy code to environments
Needs to copy data between environments (production → local, staging → local)
Wants to reset, backup, or restore an installation
Needs database or shell access to remote environments
Asks about environment configuration or available commands
Has issues with their local/staging/production environment

Symptoms and triggers:

"I need production data locally"
"How do I deploy to staging?"
"My local is broken, reset it"
"Get a shell on production"
"Check the database on staging"
"What's my current configuration?"

Smart Execution Rules

Read-Only Commands (Can Suggest Immediately)

These commands are safe to recommend without confirmation:

list, list:hosts, list:blueprints, list:backups
about, version, get:property, find:property, output
shell (but warn if production: "Be careful - full access to production")
db:shell, db:query for SELECT queries (warn about write operations)
get:file, get:files-dump, get:sql-dump, get:backup

Note: For command help, use: phab <command> --help

Destructive Commands (ALWAYS Confirm First)

These commands modify data or state - REQUIRE explicit user confirmation:

copy-from - Overwrites destination database/files, auto-runs reset
restore - Overwrites current state with backup
reset - Resets application to known state (reverts config, clears cache, resets admin password on dev)
backup - Creates backup snapshots
deploy - Deploys code (auto-backs up on non-dev, auto-resets after)
install, install:from - New installations
app:destroy - Destroys app (NO BACKUP!)
db:drop, restore:sql-from-file - Database operations
drush - Can run destructive Drupal commands (enable/disable modules, config changes, etc.)

Confirmation Protocol for Destructive Operations

CRITICAL: ALWAYS follow these steps before suggesting destructive operations. Do NOT skip steps or add concerns beyond this protocol.

Required workflow for copy-from, reset, restore, app:destroy:

ALWAYS check uncommitted work FIRST (for reset, copy-from):
- Ask: "Do you have any uncommitted code changes that need to be saved?"
- Wait for response before proceeding
ALWAYS explain what will happen:
- "This will overwrite your local database with production data"
- "reset will revert config changes, clear cache, and reset admin password (dev only)"
- "deploy will backup (non-dev), deploy code, then run reset"
ALWAYS suggest backup first (unless operation auto-backs up like deploy):
- "Want to create a backup first? phab backup"
ALWAYS get explicit confirmation:
- "Ready to proceed with phab copy-from production?"
ONLY THEN provide the command

For reset operations - MUST ask diagnostic questions:

Before suggesting reset, ALWAYS ask: "What error are you seeing? What's not working?"
Suggest less destructive alternatives first (clear cache, run composer, deploy)
Only suggest reset after diagnostics and user confirms alternatives won't work

Production Environment Extra Warnings

When suggesting ANY operation on production:

Add warning: "⚠️ This affects PRODUCTION - please double-check"
For shell access: "Be careful - you'll have full access to production"
For deploy: "Are you sure? This will deploy to PRODUCTION"

Environment Context Awareness

Understanding Default Behavior

No --config flag = ddev (local development environment)
Commands without --config execute on ddev by default

Environment Types

ddev (Local Development):

Code is already present (local development folder)
deploy on ddev: Valid but unusual (runs reset/composer)
When user says "deploy my changes" they usually mean remote environments
Common operations: copy-from, reset, backup

Remote Environments (staging, production, live, etc.):

Require --config=<environment> flag
deploy is the primary operation
Shell access needs production warnings
Example: phab --config=staging deploy

Handling Ambiguous Requests

User says: "I need to deploy my changes"

Don't assume ddev (even though it's default)
ALWAYS ask which environment, but suggest remote environments FIRST:
- "Which environment do you want to deploy to? Usually this means staging or production."
- "Note: In ddev, your code is already there since it's local development. Deploy typically means remote environments."
Preference order when ambiguous: staging → production → ddev (list in this order)
Only suggest ddev deployment if user specifically mentions local or ddev

User says: "I need production data"

Likely means: phab copy-from production to local ddev
Check for uncommitted work first
Suggest backup before overwriting

Important Command Behaviors

Auto-Backup/Reset Behaviors

deploy: Automatically backs up database (non-dev/test), then resets after success
copy-from: Automatically runs reset after copying (unless --skip-reset)
When these auto-backup/reset, you can mention it: "deploy will automatically backup first"

Command Options

copy-from <source> [what] where [what] = db, files, or omitted (both)
--skip-reset - Skip automatic reset after copy-from
--skip-drop-db - Don't drop database before import (use cautiously)
backup [what] where [what] = db, files, or omitted (both)

Undocumented Command

db:query "SQL QUERY" - Executes SQL directly (not in official docs but available)
Example: phab --config=staging db:query "SELECT * FROM users LIMIT 10"

Command Reference

Information & Discovery

List commands and hosts:

phab list                    # Show all available commands
phab list:hosts             # List configured hosts
phab list:hosts -v          # Verbose (shows descriptions & URLs)
phab list:blueprints        # Show blueprint configurations
phab list:backups           # Display available backups

Get help:

phab <command> --help        # Get help for specific command
# Example: phab deploy --help

Get configuration info:

phab about                          # Show ddev configuration
phab --config=staging about         # Show staging configuration
phab --config=staging about -v      # Include inheritance sources
phab version                        # Show installed code version
phab get:property docker.service    # Get specific property
phab find:property                  # Interactive property search
phab output                         # Print computed config as YAML

Development Workflow

Shell access:

phab shell                      # Open shell on ddev (local)
phab --config=staging shell     # Open shell on staging
phab --config=production shell  # ⚠️ Production shell (warn user!)

Deploy code:

phab --config=staging deploy           # Deploy latest to staging
phab --config=staging deploy branch    # Deploy specific branch
phab --config=production deploy        # ⚠️ Deploy to production

Note: deploy auto-backs up (non-dev) and auto-resets after

Reset installation:

phab reset              # Reset ddev to known state
phab --config=staging reset

Note: Reverts config, clears cache, runs updates, resets admin password (dev) - CONFIRM first!

Data Management

Backup:

phab backup              # Backup ddev (db + files)
phab backup db           # Backup database only
phab backup files        # Backup files only
phab --config=staging backup

Copy data between environments:

phab copy-from production           # Copy db + files from production
phab copy-from production db        # Copy database only
phab copy-from staging files        # Copy files only
phab copy-from production --skip-reset      # Skip auto-reset
phab copy-from staging --skip-drop-db      # Don't drop db (risky!)

Note: Auto-runs reset after copying (unless --skip-reset)

Restore backup:

phab restore <commit-hash>      # Restore from backup
phab list:backups               # First, see available backups

Database Operations

Execute SQL queries directly (RECOMMENDED):

# Use db:query for quick database queries (fastest method)
phab db:query "SELECT * FROM users LIMIT 10"
phab --config=staging db:query "SELECT id, name FROM users WHERE status=1"
phab --config=staging db:query "DESCRIBE users"

Note: Safe for SELECT queries, warn about INSERT/UPDATE/DELETE

Interactive database access:

phab db:shell                       # Open database client on ddev
phab --config=staging db:shell      # Open database client on staging

For Drupal sites:

phab drush "sql-query 'SELECT * FROM users LIMIT 10'"     # Run SQL query
phab --config=staging drush "sql-query 'SELECT ...'"

Note: drush can run destructive commands - confirm before suggesting config changes, module operations, etc.

File Operations

Download files:

phab get:file /path/to/remote/file          # Download specific file
phab get:files-dump                         # Download tar of files folder
phab get:sql-dump                           # Download database dump
phab --config=production get:backup <hash>  # Download backup locally

Upload files:

phab put:file /path/to/local/file
phab put:file /path/to/local/file --destination=/remote/path

Common Workflows

Workflow 1: Refresh Local with Production Data

Scenario: User needs fresh production data for debugging

Safe approach:

Check for uncommitted work:
```
git status
```
Backup current local state:
```
phab backup
```
Explain what will happen: "This will overwrite your local database with production data"
Get confirmation, then execute:
```
phab copy-from production
```
Note: Auto-runs reset after copying

Alternative - database only:

phab backup db
phab copy-from production db

Workflow 2: Safe Deployment

Scenario: User wants to deploy changes

First, clarify environment:

Ask: "Which environment? staging, production, or local ddev?"
If ambiguous, suggest staging first (for testing)

Safe deployment to staging:

# 1. Ensure code is committed
git status
git push

# 2. Deploy to staging (auto-backs up, auto-resets)
phab --config=staging deploy

# 3. Test in staging
# 4. Only then deploy to production if all looks good

Deployment to production (extra careful):

# ⚠️ Extra confirmation needed
phab --config=production deploy

Note: Auto-backs up database before deploying

Workflow 3: Troubleshooting Before Reset

Scenario: User's environment is "broken" and they want to reset

Don't jump straight to reset - diagnose first:

Ask what's actually broken: "What error are you seeing? What's not working?"

Try less destructive fixes first:

# Maybe just need to update code?
phab deploy

# Or clear cache (Drupal)?
phab drush "cc all -y"

# Or run composer?
phab shell
# then: composer install

Only if those don't work, suggest reset:
- Check for uncommitted work first!
- Backup current state
- Explain: "reset reverts config changes, clears cache, runs updates, and resets admin password"
- Get confirmation
```
phab backup
phab reset
```
If still broken, suggest fresh install from production:
```
phab copy-from production
```

Workflow 4: Database Inspection

Scenario: User wants to check data in remote database

Quick query (read-only):

# Direct query (fastest)
phab --config=staging db:query "SELECT * FROM users LIMIT 10"

# Or open interactive shell
phab --config=staging db:shell
# Then run SQL commands interactively

For Drupal:

phab --config=staging drush "sql-query 'SELECT * FROM users LIMIT 10'"

Best practices:

Use LIMIT to avoid overwhelming output
Start with DESCRIBE table_name to see structure
Read-only queries (SELECT) are safe - no confirmation needed

Workflow 5: Shell Access to Remote

Scenario: User needs command-line access to environment

For non-production:

phab --config=staging shell

For production (extra warning):

phab --config=production shell

⚠️ Warn: "Be careful - you'll have full access to production. Suggest read-only operations when possible."

Common shell use cases:

Check logs: tail -f /var/log/...
Check disk space: df -h
Check processes: ps aux | grep php
Run app-specific commands

Workflow 6: Environment Comparison

Scenario: User wants to compare configurations

Get configuration output:

phab --config=staging output > staging-config.yaml
phab --config=production output > production-config.yaml
diff staging-config.yaml production-config.yaml

Check specific properties:

phab --config=staging get:property database.name
phab --config=production get:property database.name

Common Mistakes to Avoid

Forgetting --config flag for remote environments
- Without --config, commands run on ddev (local)
- Always specify --config for staging/production
Not checking uncommitted work before reset/copy-from
- These operations can lose local changes
- Always check git status first
Not backing up before destructive operations
- Create safety net with phab backup
- Especially important for local development
Assuming "deploy" means remote when user might mean ddev
- Always clarify which environment
- "deploy my changes" usually means staging/production
Running destructive commands on production without double-checking
- Extra confirmation for production operations
- Consider consequences carefully

phabalicious

Safety Notice

Copy this and send it to your AI assistant to learn