pwcli/docs/help.md

# pwcli Help Documentation

**pwcli** is a CLI for Photowall platform that provides commands for deployment, AWS operations, workflow automation, and more.

## Quick Command Reference

```
pwcli
├── ai (ai)
│   ├── schema (sc) .................................... ai sc
│   └── promptcontextlibrary (pcl) ..................... ai pcl
│
├── aws (a)
│   ├── ecs (e)
│   │   └── sshtestserver (sts) ....................... a e sts
│   ├── logs (l) ....................................... a l
│   ├── parameterstore (ps)
│   │   ├── bulk-create (bc) .......................... a ps bc
│   │   ├── create (c) ................................ a ps c
│   │   ├── list (l) .................................. a ps l
│   │   └── update (u) ................................ a ps u
│   ├── pipeline (pl)
│   │   └── status (s) ................................ a pl s
│   └── s3 (s3)
│       ├── clear_prints (cp) ......................... a s3 cp
│       ├── print_on_station (pos) .................... a s3 pos
│       └── sync_images (si) .......................... a s3 si
│
├── deployment (d)
│   └── testservers (ts)
│       ├── create (c) ................................ d ts c
│       ├── delete (d) ................................ d ts d
│       ├── grab (g) .................................. d ts g
│       ├── status (s) ................................ d ts s
│       └── update (u) ................................ d ts u
│
├── mandrill (m)
│   └── fix_template (ft) .............................. m ft
│
├── setup (s)
│   └── settings (se) .................................. s se
│
├── test (t)
│   └── routes (r) ..................................... t r
│
├── update (up) ........................................ up
│
└── workflow (wf)
    ├── git (g)
    │   ├── clean_local_branches (clb) ................ wf g clb
    │   └── clean_old_branches (cb) ................... wf g cb
    └── setupissue (si) ................................ wf si
```

## Usage

Run `pwcli` to start the interactive menu, or use command shortcuts directly:

```bash
pwcli [command] [subcommand] [action]
```

### Command Shortcuts

Commands can be executed using their aliases. For example:
- `pwcli d ts s` → deployment testservers status
- `pwcli a ps l` → aws parameterstore list
- `pwcli wf g cb` → workflow git clean_old_branches

---

## Available Commands

### 🤖 **ai** (alias: `ai`)
AI-related commands

#### Subcommands:
- **schema** (alias: `sc`) - Output detailed pwcli command schema for LLM usage
- **promptcontextlibrary** (alias: `pcl`) - Copy context files to clipboard for AI prompts

**Examples:**
- `pwcli ai sc`
- `pwcli ai pcl`

---

### ☁️ **aws** (alias: `a`)
AWS operations and management

#### Subcommands:

##### **ecs** (alias: `e`) - Working with ECS on AWS
- **sshtestserver** (alias: `sts`) - SSH into a test server in ECS

**Example:** `pwcli a e sts`

##### **logs** (alias: `l`) - Tail a log in CloudWatch (WIP)

**Example:** `pwcli a l`

##### **parameterstore** (alias: `ps`) - Working with parameter store on AWS
- **bulk-create** (alias: `bc`) - Bulk create parameters from JSON file
- **create** (alias: `c`) - Create a new item in parameter store
- **list** (alias: `l`) - List all parameters in parameter store
- **update** (alias: `u`) - Update an existing item in parameter store

**Examples:**
- `pwcli a ps l` - List parameters
- `pwcli a ps c` - Create parameter
- `pwcli a ps bc` - Bulk create from JSON file

##### **pipeline** (alias: `pl`) - Pipeline operations
- **status** (alias: `s`) - View pipeline status with live tracking

**Example:** `pwcli a pl s`

##### **s3** (alias: `s3`) - Working with S3 on AWS
- **clear_prints** (alias: `cp`) - Clear prints-dev bucket on S3
- **print_on_station** (alias: `pos`) - Print on a real station (copies from dev to production)
- **sync_images** (alias: `si`) - Sync images between S3 buckets

**Examples:**
- `pwcli a s3 si` - Sync images
- `pwcli a s3 cp` - Clear prints

---

### 🚀 **deployment** (alias: `d`)
Deployment and test server management

#### Subcommands:

##### **testservers** (alias: `ts`) - Deploy to testservers
- **create** (alias: `c`) - Create new testserver on AWS
- **delete** (alias: `d`) - Choose a testserver to delete
- **grab** (alias: `g`) - Auto-pick a free testserver and update it with your current branch
  - Picks the "most free" server using this priority: branch is `master` → issue closed → last commit >1 month → no linked issue. Only uses servers with numbers (ex: `-3`, `-12`) and excludes failed/in-progress stacks.
  - If your branch is already deployed on a server, exits early with the URL.
  - If no free servers are found, prints the full status table.
  - Flags:
    - `--dry-run` - Show which server would be picked and why, without deploying
    - `--skip-confirm` / `-y` - Skip the confirmation prompt
    - `--json` - Output result in JSON format (implies `--skip-confirm`)
- **status** (alias: `s`) - Show status for available testservers
  - Flags:
    - `--json` - Output status information in JSON format (non-interactive)
- **update** (alias: `u`) - Update stack with different branch
  - Flags:
    - `--branch <branch>` - Specify GitHub branch to deploy
    - `--stack <stack>` - Specify test stack (formats: `photowall-test-01`, `test-01`, or `01`)
    - `--skip-confirm` - Skip confirmation prompt when using parameters
    - `--json` - Output result in JSON format with success flag and message

**Examples:**
- `pwcli d ts s` - View testserver status (interactive)
- `pwcli d ts s --json` - View testserver status as JSON
- `pwcli d ts c` - Create new testserver
- `pwcli d ts g` - Auto-grab a free testserver with your current branch
- `pwcli d ts g --dry-run` - Preview which server would be grabbed and why
- `pwcli d ts g --skip-confirm` - Grab without confirmation prompt
- `pwcli d ts u` - Update existing testserver (interactive)
- `pwcli d ts u --branch feature/123 --stack test-01` - Update test-01 with feature/123 branch (with confirmation)
- `pwcli d ts u --branch feature/123 --stack test-01 --skip-confirm` - Update without confirmation
- `pwcli d ts u --branch feature/123 --stack 01 --skip-confirm --json` - Update and output JSON result

---

### 📧 **mandrill** (alias: `m`)
Mandrill/Mailchimp email template operations

#### Subcommands:
- **fix_template** (alias: `ft`) - Remove incorrect artifacts caused by Mailchimp export to Mandrill

**Example:** `pwcli m ft`

---

### ⚙️ **setup** (alias: `s`)
Setup pwcli configuration

#### Subcommands:
- **settings** (alias: `se`) - Setup settings for pwcli (GitHub token, repo paths, API keys, etc.)

**Example:** `pwcli setup settings` or `pwcli s se`

---

### 🧪 **test** (alias: `t`)
Test commands

#### Subcommands:
- **routes** (alias: `r`) - Test pre-configured routes for 200 status on configured localhost

**Example:** `pwcli t r`

---

### 🔄 **update** (alias: `up`)
Update pwcli to the latest version from main branch and rebuild

**Example:** `pwcli update` or `pwcli up`

---

### 🔧 **workflow** (alias: `wf`)
Workflow tools for development

#### Subcommands:

##### **git** (alias: `g`) - Tools for git to make repo life easier
- **clean_local_branches** (alias: `clb`) - Clean local branches without origin connection
- **clean_old_branches** (alias: `cb`) - Prune remote and clean local branches if gone

**Examples:**
- `pwcli wf g cb` - Clean old branches
- `pwcli wf g clb` - Clean local branches

##### **setupissue** (alias: `si`) - Setup everything for an issue
Creates a new branch from origin/master based on a GitHub issue

**Example:** `pwcli wf si`

---

## Configuration

Run `pwcli setup settings` to configure:
- GitHub access token
- Local photowall repository path
- Mandrill API key
- Localhost URL and credentials for testing

Settings are stored in `~/.pwcli_settings`

---

## Tips

- Use the interactive menu by running `pwcli` without arguments
- Chain command aliases for faster execution: `pwcli d ts s`
- Most commands require AWS CLI to be installed and configured
- Some commands require settings to be configured first (run `pwcli setup settings`)

---

## Non-Interactive Mode & JSON Output

Several commands support non-interactive mode with JSON output, making them perfect for CI/CD pipelines and automation scripts.

### Testserver Status with JSON Output

Get testserver status information in JSON format:

```bash
pwcli d ts s --json
```

**JSON Output Format:**
```json
[
  {
    "name": "photowall-test-01",
    "status": "UPDATE_COMPLETE",
    "branch": "feature/123-my-feature",
    "issueNumber": "123",
    "issueStatus": "✅ open",
    "issueUpdated": "2025-11-06T10:30:00Z",
    "created": "2025-10-15T08:00:00Z",
    "updated": "2025-11-05T14:20:00Z",
    "url": "https://test-01.photowall-test.com/us"
  }
]
```

### Testserver Update - Non-Interactive

Update a testserver without interactive prompts:

```bash
pwcli d ts u --branch feature/123 --stack test-01 --skip-confirm --json
```

**Success Response:**
```json
{
  "success": true,
  "message": "Successfully updated photowall-test-01 with branch feature/123 and started pipeline",
  "stack": "photowall-test-01",
  "branch": "feature/123",
  "pipeline": "photowall-test-01Pipeline"
}
```

**Error Response:**
```json
{
  "success": false,
  "message": "Not a valid branch on photowall repo: invalid-branch"
}
```

### Automation Examples

**In a CI/CD Pipeline:**
```bash
#!/bin/bash
# Deploy to testserver and check result
result=$(pwcli d ts u --branch $CI_BRANCH --stack test-01 --skip-confirm --json)
success=$(echo $result | jq -r '.success')

if [ "$success" == "true" ]; then
  echo "Deployment successful!"
  exit 0
else
  echo "Deployment failed!"
  exit 1
fi
```

**Check testserver availability:**
```bash
# Get all testservers and find an available one
pwcli d ts s --json | jq '.[] | select(.status == "UPDATE_COMPLETE") | .name'
```

---

For more information, visit the repository or run commands interactively with `pwcli`