npm package: @lendi/ssm-cli
Description: CLI tool for AWS SSM Parameter Store operations with liam assume integration
Author: Lendi
Latest version: 0.0.1

# ssm-cli

CLI tool for AWS SSM Parameter Store operations. Authenticates via `liam assume` before every command.

## Install

From the repo root (Yarn workspaces):

```bash
yarn install
```

## Usage

```
ssm-cli -e <environment> [-r <role>] <command> [options]
```

### Global options

| Flag | Description | Default |
|---|---|---|
| `-e, --env` | **Required.** `staging` \| `development` \| `production` | — |
| `-r, --role` | `poweruser` \| `dataaccess` | `poweruser` |
| `--verbose` | Enable verbose logging | off |

### Commands

#### `put` — Create or update a parameter

```bash
# Create a String parameter
ssm-cli -e development put -n /app/config/db_host -v "db.example.com"

# Create a SecureString
ssm-cli -e production -r dataaccess put -n /app/config/db_password -v "secret" -t SecureString --key-id alias/aws/ssm

# Update (overwrite) an existing parameter — creates a new version
ssm-cli -e staging put -n /app/config/db_host -v "new-db.example.com" --overwrite
```

| Option | Description | Default |
|---|---|---|
| `-n, --name` | Parameter name (required) | — |
| `-v, --value` | Parameter value (required) | — |
| `-t, --type` | `String` \| `SecureString` | `String` |
| `--overwrite` | Overwrite if exists | `false` |
| `--key-id` | KMS key for SecureString | — |

#### `get` — Read parameter(s)

```bash
# Single parameter
ssm-cli -e staging get /app/config/db_host

# Specific version
ssm-cli -e staging get --ver 2 /app/config/db_host

# Decrypt a SecureString
ssm-cli -e production -r dataaccess get -d /app/config/db_password

# Multiple parameters at once
ssm-cli -e staging get /app/config/db_host /app/config/db_user
```

| Option | Description |
|---|---|
| `-d, --decrypt` | Decrypt SecureString values |
| `--ver <n>` | Read a specific version (single param only) |
| `--json` | Output raw JSON |

#### `get-by-path` — Read parameters by path hierarchy

```bash
ssm-cli -e staging get-by-path /app/config/

# With decryption
ssm-cli -e production -r dataaccess get-by-path /app/config/ -d

# Non-recursive
ssm-cli -e staging get-by-path /app/config/ --no-recursive
```

#### `list` — List parameters (metadata only)

```bash
ssm-cli -e staging list

# Filter by path
ssm-cli -e staging list -p /app/config/
```

#### `history` — View version history

```bash
ssm-cli -e staging history /app/config/db_host

# Limit results
ssm-cli -e staging history /app/config/db_host --max 5
```

#### `rollback` — Rollback to a previous version

Re-puts the old version's value as a new version.

```bash
ssm-cli -e staging rollback /app/config/db_host --ver 2

# Skip confirmation prompt
ssm-cli -e staging rollback /app/config/db_host --ver 2 -y
```

#### `delete` — Delete parameter(s)

**Irreversible.** Prompts for confirmation by default.

```bash
ssm-cli -e staging delete /app/config/db_host

# Delete multiple
ssm-cli -e staging delete /app/config/db_host /app/config/db_user

# Skip confirmation
ssm-cli -e staging delete /app/config/db_host -y
```

#### `tag` — Tag a parameter

```bash
ssm-cli -e staging tag /app/config/db_host --tags env=prod,team=backend
```

## Authentication

Every command runs `liam assume -e <environment> -r <role>` before executing. This:

1. Fetches temporary AWS credentials
2. May open a browser window for console login
3. Loads the exported credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`) into the session

The process waits up to 5 minutes for the browser login to complete.