@bamboo-sh/hydration-cli

CLI for triggering hydration service from CI pipelines.

Installation

npm install -g @bamboo-sh/hydration-cli
# or
pnpm add -g @bamboo-sh/hydration-cli

Usage

Hydrate a Service

Trigger a hydration for a specific service version:

hydration-cli hydrate \
  --service-name my-service \
  --version 42 \
  --env dev

Options:

• -s, --service-name <name> (required) - Name of the service to hydrate
• -v, --version <version> (required) - Version number of the service
• --stack-name <name> - CloudFormation stack name (defaults to serviceName-version)
• -e, --env <environment> - Environment suffix for SSM parameter lookup (e.g., dev, prod)
• --poll-interval <ms> - Polling interval in milliseconds (default: 10000)
• --timeout <ms> - Timeout in milliseconds (default: 7200000 / 2 hours)
• -r, --region <region> - AWS region

Sync

Trigger a sync operation:

hydration-cli sync --env dev

Options:

• -e, --env <environment> - Environment suffix for SSM parameter lookup
• --poll-interval <ms> - Polling interval in milliseconds (default: 10000)
• --timeout <ms> - Timeout in milliseconds (default: 3600000 / 1 hour)
• -r, --region <region> - AWS region

Check Execution Status

Check the status of an existing execution:

# Check status once
hydration-cli status --execution-arn arn:aws:states:...

# Wait for completion
hydration-cli status --execution-arn arn:aws:states:... --wait

Options:

• -a, --execution-arn <arn> (required) - Execution ARN to check
• --wait - Wait for execution to complete
• --poll-interval <ms> - Polling interval in milliseconds (default: 10000)
• --timeout <ms> - Timeout in milliseconds (default: 7200000)
• -r, --region <region> - AWS region

CircleCI Example

version: 2.1

jobs:
  hydrate:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install hydration CLI
          command: npm install -g @bamboo-sh/hydration-cli
      - run:
          name: Run hydration
          command: |
            hydration-cli hydrate \
              --service-name $SERVICE_NAME \
              --version $CIRCLE_BUILD_NUM \
              --env $ENVIRONMENT \
              --region ap-southeast-2

workflows:
  deploy:
    jobs:
      - hydrate:
          context: aws-credentials

Exit Codes

• 0 - Execution completed successfully
• 1 - Execution failed, timed out, or an error occurred

AWS Permissions

The CLI requires the following AWS permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/hydration-service*/step-function-arn"
    },
    {
      "Effect": "Allow",
      "Action": [
        "states:StartExecution",
        "states:DescribeExecution",
        "states:GetExecutionHistory"
      ],
      "Resource": "arn:aws:states:*:*:stateMachine:HydrationService*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "states:DescribeExecution",
        "states:GetExecutionHistory"
      ],
      "Resource": "arn:aws:states:*:*:execution:HydrationService*:*"
    }
  ]
}

Environment Variables

• AWS_REGION - AWS region (can also be set via --region flag)
• AWS_ACCESS_KEY_ID - AWS access key
• AWS_SECRET_ACCESS_KEY - AWS secret key
• AWS_SESSION_TOKEN - AWS session token (if using temporary credentials)