Mysterio CLI

A powerful, simplified command-line interface for Mysterio - configuration and secrets management for Node.js applications with AWS Secrets Manager integration.

Features

• 🚀 Simplified Commands - Only 5 core commands to remember
• 🔧 Unified Operations - Single commands for reading and writing configs
• 🌍 Environment Management - Create and manage configuration environments
• 🔐 AWS Integration - Seamless AWS Secrets Manager operations
• 📁 Local Configuration - JSON-based local config files
• 🔄 Bidirectional Sync - Sync between local and AWS
• 🔀 Custom Merge Order - Control config source priority
• 📦 Unflatten Support - Convert dotted AWS keys to nested objects

Installation

npm install -g mysterio-cli

Or use locally in your project:

npm install mysterio-cli

Quick Start

# Initialize project
mysterio init

# Create an environment
mysterio env create production

# Set configuration values
mysterio set API_KEY "secret123" --env production

# Get configuration
mysterio get --env production

# Push to AWS
mysterio aws push production

Core Commands

1. mysterio init

Initialize a new Mysterio project with configuration structure.

mysterio init [options]

Options:

• -p, --package-name <name> - Package name for the project
• -d, --config-dir <path> - Configuration directory (default: ./config)
• -e, --environments <envs...> - Initial environments (default: local, development, production)
• --aws-region <region> - AWS region (default: us-east-1)

Example:

mysterio init --name my-app --environments local staging production

2. mysterio get

Retrieve configuration from any source (local, AWS, or merged).

mysterio get [options]

Options:

• -e, --env <environment> - Target environment (default: NODE_ENV or local)
• -s, --source <type> - Source: local, env, aws, rc, or merged (default: merged)
• -f, --format <format> - Output format: json or env (default: json)
• -d, --config-dir <path> - Configuration directory (default: ./config)
• --save <file> - Save output to file
• --unflatten - Convert dotted keys to nested objects (for aws/merged sources)
• --merge-order <order> - Custom merge priority (comma-separated: default,env,secrets,rc)

Source Types:

• local - Base configuration from default.json
• env - Environment-specific config from {environment}.json
• aws - AWS Secrets Manager secrets
• rc - Local .mysteriorc overrides
• merged - All sources merged (default)

Examples:

# Get merged configuration for production
mysterio get --env production

# Get only AWS secrets
mysterio get --env production --source aws

# Get AWS secrets with dotted keys unflattened
mysterio get --env production --source aws --unflatten

# Save as .env file
mysterio get --env production --format env --save .env.production

# Get environment-specific config only
mysterio get --env development --source env

# Custom merge order (secrets override everything)
mysterio get --env production --merge-order default,env,rc,secrets

3. mysterio set

Set configuration values in local files or AWS.

mysterio set <key> <value> [options]

Options:

• -e, --env <environment> - Target environment (default: NODE_ENV or local)
• -t, --target <type> - Target: local, aws, or both (default: local)
• -d, --config-dir <path> - Configuration directory (default: ./config)
• -i, --interactive - Interactive mode for multiple values

Examples:

# Set a local config value
mysterio set API_URL "https://api.example.com" --env production

# Set a secret in AWS
mysterio set DB_PASSWORD "secret123" --env production --target aws

# Set in both local and AWS
mysterio set API_KEY "key123" --env production --target both

# Interactive mode for multiple values
mysterio set --interactive --env staging

4. mysterio env

Manage configuration environments.

mysterio env <action> [name] [options]

Actions:

• create <name> - Create new environment
• list - List all environments
• delete <name> - Delete an environment

Options:

• -d, --config-dir <path> - Configuration directory (default: ./config)
• --from <env> - Create from template environment
• --with-aws - Also manage in AWS Secrets Manager
• --show-aws - Show AWS status when listing
• --force - Force deletion without recovery (AWS)
• --days <days> - Recovery window for AWS deletion (7-30)

Examples:

# Create new environment
mysterio env create staging

# Create from template
mysterio env create qa --from production

# Create with AWS secret
mysterio env create production --with-aws

# List environments with AWS status
mysterio env list --show-aws

# Delete environment (local and AWS)
mysterio env delete old-env --with-aws --force

5. mysterio aws

AWS Secrets Manager operations.

mysterio aws <action> <environment> [options]

Actions:

• push - Push local config to AWS
• pull - Pull AWS secrets to local
• sync - Bidirectional sync
• delete - Delete AWS secret

Options:

• -p, --package-name <name> - Package name (defaults to .mysteriorc)
• -r, --region <region> - AWS region (default: us-east-1)
• -d, --config-dir <path> - Configuration directory (default: ./config)
• --override - Override existing without prompting
• --prefer <source> - For sync: prefer local or aws (default: local)
• --force - For delete: immediate deletion without recovery
• --days <days> - For delete: recovery window (7-30)

Examples:

# Push local config to AWS
mysterio aws push production

# Pull AWS secrets to local
mysterio aws pull production --override

# Sync with local preference
mysterio aws sync staging --prefer local

# Delete AWS secret with recovery
mysterio aws delete old-env --days 7

Configuration Structure

.mysteriorc

Project settings file:

{
  "packageName": "my-app",
  "configDirPath": "./config",
  "awsRegion": "us-east-1"
}

Configuration Files

Stored as JSON in your config directory:

• default.json - Shared default configuration
• [environment].json - Environment-specific configuration

Example default.json:

{
  "packageName": "my-app",
  "region": "us-east-1",
  "apiVersion": "v1"
}

Example production.json:

{
  "environment": "production",
  "debug": false,
  "apiUrl": "https://api.example.com"
}

AWS Secrets Naming

Secrets are stored in AWS Secrets Manager as:

[packageName]/[environment]

Example: my-app/production

Merge Order

When using --source merged, configuration sources are merged in this default order (later sources override earlier ones):

1. default - config/default.json
2. env - config/{environment}.json
3. secrets - AWS Secrets Manager
4. rc - .mysteriorc (local overrides)

Customize with --merge-order:

# Make AWS secrets override everything
mysterio get --merge-order default,env,rc,secrets

# Ignore AWS, merge only local sources
mysterio get --merge-order default,env,rc

Unflatten Dotted Keys

AWS Secrets Manager's Key/Value tab stores flat keys. Use --unflatten to convert dotted keys to nested objects:

# AWS secret with keys: database.host, database.port
mysterio get --source aws --unflatten

Result:

{
  "database": {
    "host": "localhost",
    "port": 5432
  }
}

Common Workflows

Local Development

# Initialize project
mysterio init

# Create local environment
mysterio env create local

# Set configuration
mysterio set DATABASE_URL "postgres://localhost:5432/dev"

# Get configuration
mysterio get

Production Setup

# Create production environment
mysterio env create production --with-aws

# Set secrets in AWS
mysterio set API_KEY "prod-key-123" --env production --target aws
mysterio set DB_PASSWORD "secret" --env production --target aws

# Get merged configuration
mysterio get --env production --source merged

Environment Cloning

# Create staging from production
mysterio env create staging --from production

# Push to AWS
mysterio aws push staging

# Modify specific values
mysterio set API_URL "https://staging-api.example.com" --env staging

Configuration Sync

# Pull AWS secrets to local
mysterio aws pull production

# Make local changes
mysterio set NEW_FEATURE "enabled" --env production

# Sync back to AWS
mysterio aws sync production --prefer local

Environment Variables

The CLI respects these environment variables:

• NODE_ENV - Default environment when not specified
• DEBUG=mysterio-cli - Enable debug logging
• AWS_ACCESS_KEY_ID - AWS credentials
• AWS_SECRET_ACCESS_KEY - AWS credentials

AWS Permissions

Required AWS IAM permissions:

• secretsmanager:GetSecretValue
• secretsmanager:CreateSecret
• secretsmanager:UpdateSecret
• secretsmanager:DeleteSecret
• secretsmanager:PutSecretValue
• secretsmanager:ListSecrets

Programmatic Usage

import {
  initMysterio,
  getConfig,
  setConfig,
  envCommand,
  awsCommand
} from 'mysterio-cli'

// Get configuration
await getConfig({
  env: 'production',
  source: 'merged',
  format: 'json'
})

// Set configuration
await setConfig('API_KEY', 'secret123', {
  env: 'production',
  target: 'aws'
})

// AWS operations
await awsCommand('push', 'production', {
  override: true
})

// Environment management
await envCommand('create', 'staging', {
  from: 'production',
  withAws: true
})

Migration from Legacy Commands

| Old Command | New Command | |------------|-------------| | mysterio read | mysterio get | | mysterio merge | mysterio get --source merged | | mysterio secrets --get | mysterio get --source aws | | mysterio secrets --set | mysterio set KEY VALUE --target aws | | mysterio create-config | mysterio aws push | | mysterio delete-config | mysterio aws delete | | mysterio list | mysterio env list |

License

Apache-2.0

Author

Yaniv Kessler

Contributing

Issues and pull requests are welcome at GitHub.

Related

• Mysterio - Core configuration and secrets management library