apcdeploy

A declarative CLI tool for managing AWS AppConfig deployments. Manage your AppConfig applications, configuration profiles, and environments as code using a simple YAML configuration file.

Note: This tool only supports AWS AppConfig hosted configuration store. You must create AppConfig resources (application, configuration profile, environment, deployment strategy) before using this tool.

Screen.Recording.2025-10-11.at.23.55.30.mov

Features

• Resource Discovery: List all AWS AppConfig resources (applications, profiles, environments) in a region
• Declarative Configuration: Define your AppConfig resources in apcdeploy.yml
• Deployment Automation: Deploy configuration changes with a single command
• Configuration Retrieval: Fetch deployed configuration (get) or sync local files with deployed state (pull)
• Deployment Rollback: Stop ongoing deployments with a single command
• Diff Previews: See exactly what will change before deploying
• Status Monitoring: Track deployment progress and completion
• Multiple Content Types: Support for both Feature Flags and Freeform configuration profiles
• Idempotent Deployments: Automatically skips deployment when local content matches deployed version

Installation

Homebrew

brew install koh-sh/tap/apcdeploy

mise

mise use -g github:koh-sh/apcdeploy

Pre-built Binary

Download the latest release from the Releases page.

Quick Start Tutorial

Tip

Working with an AI coding assistant like Claude Code? Have it run apcdeploy context to access comprehensive guidelines and usage details for this tool.

This tutorial walks you through the complete workflow: initializing from existing AWS AppConfig resources, making changes, and deploying.

Prerequisites

• AWS credentials configured (via ~/.aws/credentials, environment variables, or IAM role)
• An existing AppConfig application, configuration profile, and environment in AWS

Step 1: Initialize from Existing Resources

Generate an apcdeploy.yml file from your existing AppConfig resources using the interactive mode:

apcdeploy init

The command will guide you through:

1. Selecting an AWS region
2. Choosing an application
3. Selecting a configuration profile
4. Choosing an environment

Alternatively, you can skip the interactive prompts by providing flags:

apcdeploy init \
  --region us-west-2 \
  --app my-application \
  --profile my-config-profile \
  --env production

This creates two files:

• apcdeploy.yml: Your deployment configuration
• data.json (or .yaml/.txt): Your current configuration content

Example apcdeploy.yml:

application: my-application
configuration_profile: my-config-profile
environment: production
deployment_strategy: AppConfig.AllAtOnce  # optional, uses default if omitted
data_file: data.json
region: us-west-2

Step 2: Make Changes

Edit your configuration file (data.json, data.yaml, etc.):

# Edit your configuration
vim data.json

Example change:

{
  "database": {
    "host": "db.example.com",
    "port": 5432,
    "max_connections": 100
  },
  "features": {
    "cache_enabled": true,
    "debug_mode": false
  }
}

For AWS AppConfig Feature Flags format, see the AWS documentation.

Step 3: Preview Changes

See what will be deployed before actually deploying:

apcdeploy diff -c apcdeploy.yml

This shows a unified diff of changes between your local file and the currently deployed version.

Step 4: Deploy

Deploy your changes to AWS AppConfig:

apcdeploy run -c apcdeploy.yml

Step 5: Check Deployment Status

Check the status of your latest deployment:

apcdeploy status -c apcdeploy.yml

This shows the current deployment state (IN_PROGRESS, COMPLETE, or ROLLED_BACK) and progress percentage.

Configuration File Reference

apcdeploy.yml

# Required: Name of the AppConfig application
application: my-application

# Required: Name of the configuration profile
configuration_profile: my-config-profile

# Required: Name of the environment
environment: production

# Optional: Deployment strategy (defaults to AppConfig.AllAtOnce)
deployment_strategy: AppConfig.AllAtOnce

# Required: Path to your configuration data file (relative or absolute)
data_file: data.json

# Optional: AWS region (uses AWS SDK default if omitted)
region: us-west-2

Supported Content Types

• JSON: .json files (validated and auto-formatted)
• YAML: .yaml or .yml files (validated and auto-formatted)
• Plain Text: .txt files or any other extension

For FeatureFlags profiles, metadata fields (_createdAt, _updatedAt) are automatically ignored during diff and deployment comparisons.

Commands

For detailed usage information and advanced features, see llms.md.

Global Flags

All commands support these global flags:

• -c, --config: Config file path (default: apcdeploy.yml)
• -s, --silent: Suppress verbose output, show only essential information (useful for CI/CD and scripting)

ls-resources

List all AWS AppConfig resources in a region:

apcdeploy ls-resources --region us-west-2

This command helps you discover available applications, configuration profiles, and environments before running init. It's especially useful for automation and AI-assisted workflows.

Options:

• --region: AWS region (uses AWS SDK default if not specified)
• --json: Output in JSON format (useful for scripts and automation)
• --show-strategies: Include deployment strategies in output

Example with JSON output:

apcdeploy ls-resources --region us-west-2 --json

This command does not require an apcdeploy.yml file and is read-only.

init

Initialize a new apcdeploy.yml from existing AWS resources:

apcdeploy init

Flags are optional. If omitted, you will be prompted interactively to select from available resources.

apcdeploy init \
  --region <region> \
  --app <application> \
  --profile <profile> \
  --env <environment>

Options:

• --region: AWS region
• --app: Application name
• --profile: Configuration profile name
• --env: Environment name
• -c, --config: Output config file path (default: apcdeploy.yml)
• -o, --output-data: Output data file path (auto-detected from content type if omitted)
• -f, --force: Overwrite existing files

run

Deploy configuration changes:

apcdeploy run -c apcdeploy.yml [--wait-deploy|--wait-bake] [--force]

Options:

• --wait-deploy: Wait for deployment phase to complete (until baking starts)
• --wait-bake: Wait for complete deployment including baking phase
• --force: Deploy even if content hasn't changed

Note: --wait-deploy and --wait-bake are mutually exclusive.

diff

Preview configuration changes:

apcdeploy diff -c apcdeploy.yml [--exit-nonzero]

Options:

• --exit-nonzero: Exit with code 1 if differences are found (useful in CI)

status

Check deployment status:

apcdeploy status -c apcdeploy.yml

get

Retrieve the currently deployed configuration:

apcdeploy get -c apcdeploy.yml

Note: This command uses AWS AppConfig Data API which incurs charges per API call. You will be prompted for confirmation before proceeding.

Options:

• -y, --yes: Skip confirmation prompt (for scripts and automation)

pull

Pull the latest deployed configuration and update your local data file:

apcdeploy pull -c apcdeploy.yml

This command is useful when configuration changes are made directly in the AWS Console and you want to sync your local files with the deployed state.

rollback

Stop an ongoing deployment:

apcdeploy rollback -c apcdeploy.yml

This command stops an in-progress deployment (DEPLOYING or BAKING state) by calling the AWS AppConfig StopDeployment API. It automatically detects the current ongoing deployment and stops it.

Note: This only stops deployments currently in progress. It does not revert previously completed deployments.

Options:

• -y, --yes: Skip confirmation prompt (for scripts and automation)

context

Output context information for AI assistants:

apcdeploy context