@lendi/ssm-cli 0.0.1

package/README.md

@@ -0,0 +1,141 @@
+# 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.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@lendi/ssm-cli",
+  "version": "0.0.1",
+  "description": "CLI tool for AWS SSM Parameter Store operations with liam assume integration",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "ssm-cli": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "lint": "eslint src/",
+    "format": "prettier --write src/"
+  },
+  "keywords": [
+    "aws",
+    "ssm",
+    "parameter-store",
+    "cli",
+    "lendi"
+  ],
+  "author": "Lendi",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-ssm": "^3.700.0",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "ora": "^7.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/commands/delete.js

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { deleteParameter, deleteParameters } from '../services/ssm.js';
+import chalk from 'chalk';
+import ora from 'ora';
+import readline from 'readline';
+
+async function confirm(message) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N): `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase().trim() === 'y');
+    });
+  });
+}
+
+const deleteCommand = new Command('delete')
+  .description('Delete SSM parameter(s) — this is irreversible!')
+  .argument('<names...>', 'One or more parameter names to delete')
+  .option('-y, --yes', 'Skip confirmation', false)
+  .action(async (names, opts) => {
+    if (!opts.yes) {
+      logger.warning(chalk.red('This action is IRREVERSIBLE.'));
+      const ok = await confirm(`Delete ${names.length} parameter(s)?\n  ${names.join('\n  ')}\n`);
+      if (!ok) {
+        logger.info('Aborted');
+        return;
+      }
+    }
+
+    const spinner = ora('Deleting parameter(s)...').start();
+    try {
+      if (names.length === 1) {
+        await deleteParameter({ name: names[0] });
+        spinner.succeed(`Deleted: ${names[0]}`);
+      } else {
+        const result = await deleteParameters({ names });
+        spinner.succeed(`Deleted ${result.deleted?.length || 0} parameter(s)`);
+        if (result.invalid?.length) {
+          logger.warning(`Invalid/not found: ${result.invalid.join(', ')}`);
+        }
+      }
+    } catch (err) {
+      spinner.fail('Delete failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default deleteCommand;

package/src/commands/get.js

@@ -0,0 +1,88 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { getParameter, getParameters, getParametersByPath } from '../services/ssm.js';
+import ora from 'ora';
+
+const getCommand = new Command('get')
+  .description('Read SSM parameter(s)')
+  .argument('<names...>', 'One or more parameter names')
+  .option('-d, --decrypt', 'Decrypt SecureString values', false)
+  .option('--ver <version>', 'Read a specific parameter version')
+  .option('--json', 'Output raw JSON', false)
+  .action(async (names, opts) => {
+    const spinner = ora('Reading parameter(s)...').start();
+    try {
+      if (names.length === 1) {
+        const param = await getParameter({
+          name: names[0],
+          withDecryption: opts.decrypt,
+          version: opts.ver,
+        });
+        spinner.stop();
+        if (opts.json) {
+          logger.json(param);
+        } else {
+          logger.param(param.Name, param.Value, param.Type);
+          logger.info(`Version: ${param.Version} | Last modified: ${param.LastModifiedDate}`);
+        }
+      } else {
+        const { parameters, invalidParameters } = await getParameters({
+          names,
+          withDecryption: opts.decrypt,
+        });
+        spinner.stop();
+        if (opts.json) {
+          logger.json(parameters);
+        } else {
+          for (const p of parameters) {
+            logger.param(p.Name, p.Value, p.Type);
+          }
+          if (invalidParameters?.length) {
+            logger.warning(`Invalid parameters: ${invalidParameters.join(', ')}`);
+          }
+        }
+      }
+    } catch (err) {
+      spinner.fail('Failed to read parameter(s)');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+const getByPathCommand = new Command('get-by-path')
+  .description('Read SSM parameters by path hierarchy')
+  .argument('<path>', 'Parameter path prefix (e.g. /app/config/)')
+  .option('-d, --decrypt', 'Decrypt SecureString values', false)
+  .option('--no-recursive', 'Do not recurse into sub-paths')
+  .option('--json', 'Output raw JSON', false)
+  .action(async (path, opts) => {
+    const spinner = ora(`Reading parameters under ${path}...`).start();
+    try {
+      const params = await getParametersByPath({
+        path,
+        recursive: opts.recursive,
+        withDecryption: opts.decrypt,
+      });
+      spinner.stop();
+
+      if (params.length === 0) {
+        logger.info('No parameters found');
+        return;
+      }
+
+      if (opts.json) {
+        logger.json(params);
+      } else {
+        logger.info(`Found ${params.length} parameter(s):`);
+        for (const p of params) {
+          logger.param(p.Name, p.Value, p.Type);
+        }
+      }
+    } catch (err) {
+      spinner.fail('Failed to read parameters by path');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export { getCommand, getByPathCommand };

package/src/commands/history.js

@@ -0,0 +1,44 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { getParameterHistory } from '../services/ssm.js';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const historyCommand = new Command('history')
+  .description('View version history of an SSM parameter')
+  .argument('<name>', 'Parameter name')
+  .option('--max <n>', 'Max results', parseInt)
+  .option('--json', 'Output raw JSON', false)
+  .action(async (name, opts) => {
+    const spinner = ora(`Fetching history for ${name}...`).start();
+    try {
+      const entries = await getParameterHistory({
+        name,
+        maxResults: opts.max,
+      });
+      spinner.stop();
+
+      if (entries.length === 0) {
+        logger.info('No history found');
+        return;
+      }
+
+      if (opts.json) {
+        logger.json(entries);
+      } else {
+        logger.info(`${entries.length} version(s) of ${chalk.bold(name)}:\n`);
+        for (const e of entries) {
+          const type = e.Type === 'SecureString' ? chalk.red(e.Type) : chalk.green(e.Type);
+          console.log(
+            `  v${e.Version}  ${type}  ${chalk.gray(e.LastModifiedDate?.toISOString() || '')}  by ${e.LastModifiedUser || 'unknown'}`
+          );
+        }
+      }
+    } catch (err) {
+      spinner.fail('Failed to get parameter history');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default historyCommand;

package/src/commands/list.js

@@ -0,0 +1,42 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { describeParameters } from '../services/ssm.js';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const listCommand = new Command('list')
+  .description('List SSM parameters (metadata only)')
+  .option('-p, --path <path>', 'Filter by path prefix (recursive)')
+  .option('--max <n>', 'Max results per page', parseInt)
+  .option('--json', 'Output raw JSON', false)
+  .action(async (opts) => {
+    const spinner = ora('Listing parameters...').start();
+    try {
+      const params = await describeParameters({
+        path: opts.path,
+        maxResults: opts.max,
+      });
+      spinner.stop();
+
+      if (params.length === 0) {
+        logger.info('No parameters found');
+        return;
+      }
+
+      if (opts.json) {
+        logger.json(params);
+      } else {
+        logger.info(`Found ${params.length} parameter(s):\n`);
+        for (const p of params) {
+          const type = p.Type === 'SecureString' ? chalk.red(p.Type) : chalk.green(p.Type);
+          console.log(`  ${chalk.bold(p.Name)}  ${chalk.gray(type)}  v${p.Version || '?'}  ${chalk.gray(p.LastModifiedDate?.toISOString() || '')}`);
+        }
+      }
+    } catch (err) {
+      spinner.fail('Failed to list parameters');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default listCommand;

package/src/commands/put.js

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { putParameter } from '../services/ssm.js';
+import ora from 'ora';
+
+const putCommand = new Command('put')
+  .description('Create or update an SSM parameter')
+  .requiredOption('-n, --name <name>', 'Parameter name (e.g. /app/config/db_host)')
+  .requiredOption('-v, --value <value>', 'Parameter value')
+  .option('-t, --type <type>', 'Parameter type: String | SecureString', 'String')
+  .option('--overwrite', 'Overwrite existing parameter (creates new version)', false)
+  .option('--key-id <keyId>', 'KMS key ID for SecureString (e.g. alias/aws/ssm)')
+  .action(async (opts) => {
+    const spinner = ora('Putting parameter...').start();
+    try {
+      const result = await putParameter({
+        name: opts.name,
+        value: opts.value,
+        type: opts.type,
+        overwrite: opts.overwrite,
+        keyId: opts.keyId,
+      });
+      spinner.succeed(`Parameter ${opts.overwrite ? 'updated' : 'created'}: ${opts.name}`);
+      logger.info(`Version: ${result.version}`);
+    } catch (err) {
+      spinner.fail('Failed to put parameter');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default putCommand;

package/src/commands/rollback.js

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { rollbackParameter } from '../services/ssm.js';
+import ora from 'ora';
+import readline from 'readline';
+
+async function confirm(message) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N): `, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase().trim() === 'y');
+    });
+  });
+}
+
+const rollbackCommand = new Command('rollback')
+  .description('Rollback a parameter to a previous version (re-puts old value as new version)')
+  .argument('<name>', 'Parameter name')
+  .requiredOption('--ver <version>', 'Version to rollback to')
+  .option('-t, --type <type>', 'Override parameter type (default: keeps original type)')
+  .option('-y, --yes', 'Skip confirmation', false)
+  .action(async (name, opts) => {
+    if (!opts.yes) {
+      const ok = await confirm(
+        `Rollback ${name} to version ${opts.ver}?`
+      );
+      if (!ok) {
+        logger.info('Aborted');
+        return;
+      }
+    }
+
+    const spinner = ora('Rolling back...').start();
+    try {
+      const result = await rollbackParameter({
+        name,
+        version: parseInt(opts.ver, 10),
+        type: opts.type,
+      });
+      spinner.succeed(`Rolled back ${name} → new version ${result.version}`);
+    } catch (err) {
+      spinner.fail('Rollback failed');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default rollbackCommand;

package/src/commands/tag.js

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+import logger from '../utils/logger.js';
+import { tagParameter } from '../services/ssm.js';
+import ora from 'ora';
+
+const tagCommand = new Command('tag')
+  .description('Add tags to an SSM parameter')
+  .argument('<name>', 'Parameter name')
+  .requiredOption('--tags <tags>', 'Tags as Key=Value pairs, comma-separated (e.g. env=prod,team=backend)')
+  .action(async (name, opts) => {
+    const tags = opts.tags.split(',').map((pair) => {
+      const [Key, Value] = pair.split('=');
+      if (!Key || Value === undefined) {
+        logger.error(`Invalid tag format: "${pair}". Use Key=Value`);
+        process.exit(1);
+      }
+      return { Key: Key.trim(), Value: Value.trim() };
+    });
+
+    const spinner = ora('Adding tags...').start();
+    try {
+      await tagParameter({ name, tags });
+      spinner.succeed(`Tagged ${name} with ${tags.length} tag(s)`);
+    } catch (err) {
+      spinner.fail('Failed to add tags');
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+export default tagCommand;

package/src/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import logger from './utils/logger.js';
+import { liamAssume, VALID_ENVIRONMENTS, VALID_ROLES } from './utils/auth.js';
+import putCommand from './commands/put.js';
+import { getCommand, getByPathCommand } from './commands/get.js';
+import listCommand from './commands/list.js';
+import historyCommand from './commands/history.js';
+import rollbackCommand from './commands/rollback.js';
+import deleteCommand from './commands/delete.js';
+import tagCommand from './commands/tag.js';
+
+const program = new Command();
+
+program
+  .name('ssm-cli')
+  .description('CLI tool for AWS SSM Parameter Store operations')
+  .version('1.0.0')
+  .option('--verbose', 'Enable verbose logging')
+  .requiredOption(
+    '-e, --env <environment>',
+    `AWS environment (${VALID_ENVIRONMENTS.join(' | ')})`
+  )
+  .option(
+    '-r, --role <role>',
+    `IAM role (${VALID_ROLES.join(' | ')})`,
+    'poweruser'
+  )
+  .hook('preAction', async (thisCommand) => {
+    if (thisCommand.opts().verbose) {
+      process.env.VERBOSE = 'true';
+    }
+
+    const { env, role } = thisCommand.opts();
+
+    // Authenticate via liam assume before running any sub-command
+    try {
+      await liamAssume(env, role);
+    } catch (err) {
+      logger.error(err.message);
+      process.exit(1);
+    }
+  });
+
+// Register sub-commands
+program.addCommand(putCommand);
+program.addCommand(getCommand);
+program.addCommand(getByPathCommand);
+program.addCommand(listCommand);
+program.addCommand(historyCommand);
+program.addCommand(rollbackCommand);
+program.addCommand(deleteCommand);
+program.addCommand(tagCommand);
+
+program.addHelpText(
+  'after',
+  `
+Examples:
+  # Read a parameter from staging
+  $ ssm-cli -e staging get /app/config/db_host
+
+  # Read with decryption
+  $ ssm-cli -e production -r dataaccess get -d /app/config/db_password
+
+  # Create a new 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
+
+  # Update (overwrite) a parameter
+  $ ssm-cli -e staging put -n /app/config/db_host -v "new-db.example.com" --overwrite
+
+  # List all parameters under a path
+  $ ssm-cli -e staging get-by-path /app/config/
+
+  # List parameter metadata
+  $ ssm-cli -e staging list -p /app/config/
+
+  # View version history
+  $ ssm-cli -e staging history /app/config/db_host
+
+  # Rollback to an old version
+  $ ssm-cli -e staging rollback /app/config/db_host --ver 2
+
+  # Delete a parameter
+  $ ssm-cli -e staging delete /app/config/db_host
+
+  # Tag a parameter
+  $ ssm-cli -e staging tag /app/config/db_host --tags env=prod,team=backend
+`
+);
+
+// Error handling
+process.on('unhandledRejection', (reason) => {
+  logger.error(`Unhandled rejection: ${reason}`);
+  process.exit(1);
+});
+
+program.parseAsync();

package/src/services/ssm.js

@@ -0,0 +1,164 @@
+import {
+  SSMClient,
+  PutParameterCommand,
+  GetParameterCommand,
+  GetParametersCommand,
+  GetParametersByPathCommand,
+  DescribeParametersCommand,
+  GetParameterHistoryCommand,
+  DeleteParameterCommand,
+  DeleteParametersCommand,
+  AddTagsToResourceCommand,
+} from '@aws-sdk/client-ssm';
+import logger from '../utils/logger.js';
+
+let client = null;
+
+function getClient() {
+  if (!client) {
+    client = new SSMClient({});
+  }
+  return client;
+}
+
+/** 1. Create / 2. Update a parameter */
+export async function putParameter({ name, value, type = 'String', overwrite = false, keyId }) {
+  const params = {
+    Name: name,
+    Value: value,
+    Type: type,
+    Overwrite: overwrite,
+  };
+  if (keyId) params.KeyId = keyId;
+
+  const result = await getClient().send(new PutParameterCommand(params));
+  return { version: result.Version, tier: result.Tier };
+}
+
+/** 3. Read a single parameter (latest) */
+export async function getParameter({ name, withDecryption = false, version }) {
+  const paramName = version ? `${name}:${version}` : name;
+  const result = await getClient().send(
+    new GetParameterCommand({
+      Name: paramName,
+      WithDecryption: withDecryption,
+    })
+  );
+  return result.Parameter;
+}
+
+/** 5. Read multiple parameters */
+export async function getParameters({ names, withDecryption = false }) {
+  const result = await getClient().send(
+    new GetParametersCommand({
+      Names: names,
+      WithDecryption: withDecryption,
+    })
+  );
+  return {
+    parameters: result.Parameters,
+    invalidParameters: result.InvalidParameters,
+  };
+}
+
+/** 6. Read parameters by path */
+export async function getParametersByPath({ path, recursive = true, withDecryption = false }) {
+  const allParams = [];
+  let nextToken;
+
+  do {
+    const result = await getClient().send(
+      new GetParametersByPathCommand({
+        Path: path,
+        Recursive: recursive,
+        WithDecryption: withDecryption,
+        NextToken: nextToken,
+      })
+    );
+    allParams.push(...(result.Parameters || []));
+    nextToken = result.NextToken;
+  } while (nextToken);
+
+  return allParams;
+}
+
+/** 7. List / describe parameters (metadata only) */
+export async function describeParameters({ path, maxResults } = {}) {
+  const allParams = [];
+  let nextToken;
+  const params = {};
+
+  if (path) {
+    params.ParameterFilters = [
+      { Key: 'Path', Option: 'Recursive', Values: [path] },
+    ];
+  }
+  if (maxResults) params.MaxResults = maxResults;
+
+  do {
+    if (nextToken) params.NextToken = nextToken;
+    const result = await getClient().send(new DescribeParametersCommand(params));
+    allParams.push(...(result.Parameters || []));
+    nextToken = result.NextToken;
+    // If maxResults is set, only fetch one page
+    if (maxResults) break;
+  } while (nextToken);
+
+  return allParams;
+}
+
+/** 8. View parameter history */
+export async function getParameterHistory({ name, maxResults }) {
+  const allHistory = [];
+  let nextToken;
+
+  do {
+    const params = { Name: name };
+    if (maxResults) params.MaxResults = maxResults;
+    if (nextToken) params.NextToken = nextToken;
+
+    const result = await getClient().send(new GetParameterHistoryCommand(params));
+    allHistory.push(...(result.Parameters || []));
+    nextToken = result.NextToken;
+    if (maxResults) break;
+  } while (nextToken);
+
+  return allHistory;
+}
+
+/** 9. Rollback – read old version, then put as new version */
+export async function rollbackParameter({ name, version, type }) {
+  logger.info(`Reading version ${version} of ${name}...`);
+  const oldParam = await getParameter({ name, version, withDecryption: true });
+  const oldValue = oldParam.Value;
+  const paramType = type || oldParam.Type;
+
+  logger.info(`Re-putting old value as new version (type: ${paramType})...`);
+  return putParameter({ name, value: oldValue, type: paramType, overwrite: true });
+}
+
+/** 10. Delete a single parameter */
+export async function deleteParameter({ name }) {
+  await getClient().send(new DeleteParameterCommand({ Name: name }));
+}
+
+/** 10. Delete multiple parameters */
+export async function deleteParameters({ names }) {
+  const result = await getClient().send(new DeleteParametersCommand({ Names: names }));
+  return {
+    deleted: result.DeletedParameters,
+    invalid: result.InvalidParameters,
+  };
+}
+
+/** 11. Tag a parameter */
+export async function tagParameter({ name, tags }) {
+  // tags = [{ Key: 'env', Value: 'prod' }, ...]
+  await getClient().send(
+    new AddTagsToResourceCommand({
+      ResourceType: 'Parameter',
+      ResourceId: name,
+      Tags: tags,
+    })
+  );
+}

package/src/utils/auth.js

@@ -0,0 +1,75 @@
+import { execSync } from 'child_process';
+import logger from './logger.js';
+import ora from 'ora';
+
+const VALID_ENVIRONMENTS = ['staging', 'development', 'production'];
+const VALID_ROLES = ['poweruser', 'dataaccess'];
+
+/**
+ * Run `liam assume <environment> <role>` and load the exported
+ * AWS credentials into the current process environment.
+ *
+ * `liam assume` prints shell export statements (and may open a
+ * browser for console login), so we capture stdout and parse
+ * the KEY=VALUE pairs.
+ */
+export async function liamAssume(environment, role) {
+  if (!VALID_ENVIRONMENTS.includes(environment)) {
+    throw new Error(
+      `Invalid environment "${environment}". Must be one of: ${VALID_ENVIRONMENTS.join(', ')}`
+    );
+  }
+  if (!VALID_ROLES.includes(role)) {
+    throw new Error(
+      `Invalid role "${role}". Must be one of: ${VALID_ROLES.join(', ')}`
+    );
+  }
+
+  const cmd = `liam assume -e ${environment} -r ${role}`;
+  const spinner = ora(`Running: ${cmd} (this may open a browser for login)...`).start();
+
+  try {
+    // liam assume outputs export statements like:
+    //   export AWS_ACCESS_KEY_ID=AKIA...
+    //   export AWS_SECRET_ACCESS_KEY=...
+    //   export AWS_SESSION_TOKEN=...
+    // We capture that output, then parse and inject into process.env
+    const output = execSync(cmd, {
+      encoding: 'utf-8',
+      // Give generous timeout – browser login may take a while
+      timeout: 5 * 60 * 1000, // 5 minutes
+      stdio: ['inherit', 'pipe', 'inherit'],
+    });
+
+    const exportLines = output
+      .split('\n')
+      .filter((line) => line.startsWith('export '));
+
+    let credCount = 0;
+    for (const line of exportLines) {
+      // export KEY=VALUE  or  export KEY="VALUE"
+      const match = line.match(/^export\s+([A-Z_]+)=["']?(.+?)["']?$/);
+      if (match) {
+        const [, key, value] = match;
+        process.env[key] = value;
+        credCount++;
+        logger.debug(`Set ${key}`);
+      }
+    }
+
+    if (credCount === 0) {
+      spinner.warn('liam assume completed but no credentials were exported');
+      logger.warning('Make sure liam is installed and the command is correct');
+    } else {
+      spinner.succeed(`Authenticated to ${environment} as ${role} (${credCount} vars loaded)`);
+    }
+  } catch (err) {
+    spinner.fail('liam assume failed');
+    if (err.status) {
+      throw new Error(`liam assume exited with code ${err.status}`);
+    }
+    throw err;
+  }
+}
+
+export { VALID_ENVIRONMENTS, VALID_ROLES };

package/src/utils/logger.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+
+class Logger {
+  constructor() {
+    this.isVerbose = process.env.VERBOSE === 'true';
+  }
+
+  info(message) {
+    console.log(chalk.blue('ℹ'), message);
+  }
+
+  success(message) {
+    console.log(chalk.green('✓'), message);
+  }
+
+  warning(message) {
+    console.log(chalk.yellow('⚠'), message);
+  }
+
+  error(message) {
+    console.error(chalk.red('✗'), message);
+  }
+
+  debug(message) {
+    if (this.isVerbose) {
+      console.log(chalk.gray('🔍'), message);
+    }
+  }
+
+  param(name, value, type) {
+    const typeColor = type === 'SecureString' ? chalk.red(type) : chalk.green(type);
+    console.log(`  ${chalk.bold(name)} ${chalk.gray('=')} ${value} ${chalk.gray(`[${typeColor}]`)}`);
+  }
+
+  json(data) {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+export const logger = new Logger();
+export default logger;