NewInstance Secret Manager

A Node.js utility for securely loading environment variables from the Secret Key Manager API.

Table of Contents

• Installation
• Configuration
• Features
• Usage
  • Basic Usage
  • Zero-Config Usage
  • Command Line Options
• Parameter Details
  • Authentication Parameters
  • Environment and Output Parameters
  • System Integration Parameters
  • Bridge System Parameters
  • .env File Creation Parameters
  • Utility Parameters
• Advanced Usage
  • Environment Variable Bridge
  • Shell Integration
  • System-Level Environment Variables
  • IDE Integration
  • Multiple Environment Sets
  • Environment Variable Inheritance
• CI/CD Integration
  • GitHub Actions
  • GitLab CI/CD
  • AWS CodePipeline
  • AWS Elastic Beanstalk
• Troubleshooting
  • Common Errors
  • Multiple Environment Sets
  • AWS Elastic Beanstalk Troubleshooting
• Cross-Platform Compatibility
• Security Best Practices
• Contributing
• License

Installation

npm install -g newinstance-secret-manager

Or use it directly with npx (Recommended) using the shorter command alias:

npx nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789"

Configuration

Environment Variables

The NewInstance Secret Manager supports configuration through environment variables:

# Use the SDK
npx nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789"

Proxy Server

For advanced deployments, a proxy server is available with comprehensive environment variable validation:

• See PROXY-SERVER.md for proxy server configuration
• See ENVIRONMENT-VARIABLES.md for complete environment variable documentation

## Features

- Securely sets environment variables from the Secret Key Manager Service
- On premise decryption using your App Secret
- Support for different environments (development, staging, production)
- Output to process.env or file (.env, JSON, shell script)
- Multiple output formats (dotenv, JSON, shell script)
- **Environment Variable Bridge** for cross-terminal access without admin privileges
- **System-level environment variables** for universal access across applications
- **Shell integration** for making variables available to the parent shell process
- **IDE integration** for development environments
- Comprehensive error handling
- Zero-config usage with environment variables
- Cross-platform compatibility (Windows, macOS, Linux)
- Short command alias (`nism`) for easier usage

## Usage

### Basic Usage

```bash
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789"

This will fetch environment variables for the development environment and set them in process.env.

Zero-Config Usage

Set the required environment variables:

export NEW_INSTANCE_APP_ID="app_123456"
export NEW_INSTANCE_API_KEY="key_abcdef"
export NEW_INSTANCE_APP_SECRET="secret_xyz789"
export NEW_INSTANCE_ENVIRONMENT="production"  # Optional, defaults to "development"

Then simply run:

nism

This will automatically use the environment variables to fetch and set the environment variables for your application.

Command Line Options

| Option | Description | Default | Environment Variable Fallback | |--------|-------------|---------|------------------------------| | --appId=<value> | The application ID | | NEW_INSTANCE_APP_ID | | --apiKey=<value> | The API key for authentication | | NEW_INSTANCE_API_KEY | | --appSecret=<value> | The app secret for decryption | | NEW_INSTANCE_APP_SECRET | | --environment=<value> | The environment to load (development, staging, production) | development | NEW_INSTANCE_ENVIRONMENT | | --output=<value> | Write to a specified file instead of setting process.env variables | | | | --silent=<value> | Suppress all non-error console output (true/false) | false | | | --format=<value> | Output format (dotenv, json, shell) | dotenv | | | --shell=<value> | Generate a shell script for sourcing (true/false) | false | | | --debug=<value> | Enable debug mode for detailed logging (true/false) | false | | | setup | Run the setup command to configure shell integration | | | | --system-level=<value> | Set system-level environment variables (true/false) | true | | | --prompt-for-elevation=<value> | Prompt for elevation when needed (true/false) | true | | | --modify-profile-files=<value> | Modify user profile files on Unix systems (true/false) | true | | | --create-startup-script=<value> | Create a startup script if system-level setting fails (true/false) | true | | | --show-warnings=<value> | Show warnings about limitations (true/false) | true | | | --bridge=<value> | Use the Environment Variable Bridge (true/false) | true | | | --bridge-storage-dir=<value> | Directory to store environment variable files | ~/.nism | | | --env-set-name=<value> | Name of the environment variable set | default | | | --auto-add-to-profile=<value> | Automatically add shell integration to profile files (true/false) | true | | | --shell-integration=<value> | Enable shell integration (true/false) | true | | | --ide-integration=<value> | Enable IDE integration (true/false) | false | | | --create-env=<value> | Create .env file with specified filename (false or filename) | false | | | --help | Display help information | | | | --version | Output the version number | | |

Note: All required parameters can be provided either as command-line arguments or as environment variables. If both are provided, the command-line arguments take precedence. This allows for zero-config usage when environment variables are set.

Parameter Details

This section provides comprehensive explanations for each CLI parameter, including usage examples and important notes.

Authentication Parameters

--appId=<value>

What it does: Specifies the unique identifier for your application in the NewInstance Secret Manager.

When to use: Required for all operations. Each application has a unique App ID that identifies which set of environment variables to retrieve.

Examples:

nism --appId="app_123456789abcdef"

Environment Variable Fallback: NEW_INSTANCE_APP_ID

Notes:

• App IDs are typically 25-character hexadecimal strings
• Can be found in your NewInstance dashboard
• Required for all operations unless set via environment variable

--apiKey=<value>

What it does: Provides the API key for authenticating with the NewInstance Secret Manager service.

When to use: Required for all service operations. Used to authenticate your requests to the service.

Examples:

nism --apiKey="key_abcdef123456789"

Environment Variable Fallback: NEW_INSTANCE_API_KEY

Notes:

• API keys start with "key_" prefix
• Should be kept secure and not exposed in logs or version control
• Can be rotated in your NewInstance dashboard

--appSecret=<value>

What it does: Provides the application secret used for on premise decryption of environment variables.

When to use: Required for all operations. Used to decrypt environment variables locally without sending the secret to the server.

Examples:

nism --appSecret="secret_xyz789abc123def456"

Environment Variable Fallback: NEW_INSTANCE_APP_SECRET

Notes:

• App secrets start with "secret_" prefix
• Never sent to the server - used only for local decryption
• Must be kept extremely secure
• If compromised, regenerate immediately in your dashboard

Environment and Output Parameters

--environment=<value>

What it does: Specifies which environment's variables to load (development, staging, production).

When to use: Use different environments for different deployment stages or configurations.

Examples:

nism --environment="development"     # Default
nism --environment="staging"
nism --environment="production"

Environment Variable Fallback: NEW_INSTANCE_ENVIRONMENT

Default: development

Notes:

• Environment names are case-sensitive
• Each environment can have different variable values
• Commonly used for separating dev/staging/prod configurations

--output=<value>

What it does: Writes environment variables to a specified file instead of setting them in the current process.

When to use: When you need to save variables to a file for later use, CI/CD pipelines, or sharing with other tools.

Examples:

nism --output=".env.local"           # Create .env.local file
nism --output="config/env.json"      # Create JSON file in config directory
nism --output="production.env"       # Environment-specific file

Notes:

• Creates the file in the specified location
• File format depends on the --format parameter
• Overwrites existing files
• Directory must exist (use --create-env for automatic directory creation)

--format=<value>

What it does: Specifies the output format for environment variables.

When to use: Choose the format that best suits your use case or target application.

Options:

• dotenv (default): Standard .env file format
• json: JSON object format
• shell: Shell script format for sourcing

Examples:

nism --format="dotenv"               # KEY=value format
nism --format="json"                 # {"KEY": "value"} format
nism --format="shell"                # export KEY="value" format

Default: dotenv

Notes:

• dotenv format is compatible with most frameworks
• json format is useful for programmatic consumption
• shell format can be sourced directly in shell scripts

--silent=<value>

What it does: Suppresses all non-error console output.

When to use: In automated scripts, CI/CD pipelines, or when you only want to see errors.

Examples:

nism --silent="true"                 # No success messages or progress indicators
nism --silent="true" --output=".env" # Only creates file, no console output
nism --silent="false"                # Default - show all output

Default: false

Notes:

• Error messages are still displayed
• Useful for scripting and automation
• Combines well with --output for file-only operations

System Integration Parameters

--system-level=<value>

What it does: Attempts to set environment variables at the system level, making them available to all applications.

When to use: When you want variables accessible across all applications and terminal sessions.

Examples:

nism --system-level="true"           # Default behavior
nism --system-level="false"          # Disable system-level setting

Default: true

Notes:

• May require administrative privileges
• Behavior varies by operating system
• Falls back to user-level or bridge system if system-level fails

--prompt-for-elevation=<value>

What it does: Controls whether to prompt for administrative privileges when needed for system-level operations.

When to use: Enable when you have admin access and want system-wide variables. Disable in automated environments.

Examples:

nism --prompt-for-elevation="true"   # Default - will prompt for admin access
nism --prompt-for-elevation="false"  # Skip elevation, use fallback methods

Default: true

Notes:

• Only relevant when --system-level is enabled
• Disable in CI/CD environments where interactive prompts aren't possible
• When disabled, falls back to user-level or bridge methods

--modify-profile-files=<value>

What it does: Controls whether to modify shell profile files (.bashrc, .zshrc, etc.) to persist environment variables.

When to use: Enable for persistent variables across shell sessions. Disable if you manage profile files manually.

Examples:

nism --modify-profile-files="true"   # Default - will modify profile files
nism --modify-profile-files="false"  # Skip profile modification

Default: true

Notes:

• Only affects Unix-like systems (Linux, macOS)
• Adds source statements to common profile files
• Disable if you prefer manual profile management

--create-startup-script=<value>

What it does: Creates a startup script as a fallback when other system-level methods fail.

When to use: As a fallback mechanism for environment variable persistence.

Examples:

nism --create-startup-script="true"  # Default - create fallback script
nism --create-startup-script="false" # Skip startup script creation

Default: true

Notes:

• Only used when system-level and profile methods fail
• Creates platform-specific startup scripts
• Provides instructions for manual execution

--show-warnings=<value>

What it does: Controls whether to display warnings about limitations or fallback methods.

When to use: Enable for detailed feedback about what methods were used. Disable for cleaner output.

Examples:

nism --show-warnings="true"          # Default - show informational warnings
nism --show-warnings="false"         # Hide warnings, show only errors

Default: true

Notes:

• Warnings provide useful information about system limitations
• Disable in automated environments for cleaner logs
• Errors are always shown regardless of this setting

Bridge System Parameters

--bridge=<value>

What it does: Enables the Environment Variable Bridge system for cross-terminal variable sharing.

When to use: Recommended for most users. Provides the best balance of convenience and security.

Examples:

nism --bridge="true"                 # Default - use bridge system
nism --bridge="false"                # Disable bridge, use only process.env

Default: true

Notes:

• Works without administrative privileges
• Enables cross-terminal variable access
• Stores variables in JSON format for persistence

--bridge-storage-dir=<value>

What it does: Specifies the directory where bridge system files are stored.

When to use: Customize storage location for organizational or security requirements.

Examples:

nism --bridge-storage-dir="~/.nism"              # Default location
nism --bridge-storage-dir="/opt/myapp/secrets"   # Custom location
nism --bridge-storage-dir="$HOME/.config/nism"   # Alternative location

Default: ~/.nism

Notes:

• Directory is created automatically if it doesn't exist
• Should be in a secure location with appropriate permissions
• Contains JSON files and shell integration scripts

--env-set-name=<value>

What it does: Specifies the name for the environment variable set, allowing multiple named configurations.

When to use: When working with multiple projects or environments that need separate variable sets.

Examples:

nism --env-set-name="default"        # Default set
nism --env-set-name="project1"       # Project-specific set
nism --env-set-name="production"     # Environment-specific set

Default: default

Notes:

• Each named set is stored separately
• Useful for multi-project development
• Can be activated independently in different terminal sessions

--auto-add-to-profile=<value>

What it does: Automatically adds shell integration commands to your shell profile files for seamless variable loading.

When to use: Enable for the best user experience - variables will be automatically available in new terminal sessions.

Examples:

nism --auto-add-to-profile="true"    # Default - automatic integration
nism --auto-add-to-profile="false"   # Disable automatic profile modification

Default: true

Notes:

• Provides the most seamless user experience
• Automatically loads variables in new terminal sessions
• Modifies .bashrc, .zshrc, and other common profile files
• Can be disabled if you prefer manual integration

--shell-integration=<value>

What it does: Controls creation of shell integration scripts.

When to use: Enable for shell access to variables. Disable when you only need JSON storage.

Examples:

nism --shell-integration="true"      # Default - create shell scripts
nism --shell-integration="false"     # Skip shell script creation

Default: true

Notes:

• When disabled, reduces bridge system functionality
• Variables won't be easily accessible in shell sessions
• JSON storage still works for programmatic access

--ide-integration=<value>

What it does: Controls IDE-specific integrations and optimizations.

When to use: Enable for enhanced IDE support and development workflow integration.

Examples:

nism --ide-integration="false"       # Default - basic functionality
nism --ide-integration="true"        # Enable IDE-specific features

Default: false

Notes:

• When enabled, may create additional IDE-specific configuration files
• Use --create-env for .env file creation instead
• Provides enhanced development environment integration

.env File Creation Parameters

--create-env=<value>

What it does: Creates a .env file in the current working directory with the loaded environment variables.

When to use: When you need a .env file for IDE integration, framework compatibility, or local development.

Examples:

nism --create-env=".env"             # Creates .env in current directory
nism --create-env=".env.local"       # Creates .env.local file
nism --create-env="config/app.env"   # Creates file in subdirectory
nism --create-env="false"            # Disable .env file creation (default)

Default: false (opt-in only)

Notes:

• When set to a filename, creates the specified file in the current working directory
• When set to "false", disables .env file creation
• Works alongside other output options (can create both .env and --output files)
• Automatically creates parent directories if needed
• Overwrites existing files

Utility Parameters

--shell=<value>

What it does: Generates a shell script that can be sourced to export variables to the parent shell.

When to use: When you need to make variables available in your current shell session.

Examples:

nism --shell="true"                  # Generates env.sh by default
nism --shell="true" --output="setup.sh"  # Custom shell script name
nism --shell="false"                 # Disable shell script generation (default)

Default: false

Notes:

• When enabled, shorthand for --format=shell --output=env.sh
• Generated script can be sourced with source env.sh
• Use --output=- to output to stdout for direct sourcing

--debug=<value>

What it does: Enables detailed debug logging to help troubleshoot issues.

When to use: When experiencing problems or when you need detailed information about the process.

Examples:

nism --debug="true"                  # Enable debug logging
nism --debug="true" --silent="true"  # Debug logs but no success messages
nism --debug="false"                 # Disable debug logging (default)

Default: false

Notes:

• Shows detailed information about NewInstance service calls, decryption, and file operations
• Environment variable verification: Automatically tests that loaded variables are accessible via native shell commands (echo $VARIABLE_NAME on Unix, echo %VARIABLE_NAME% on Windows)
• Useful for troubleshooting authentication or decryption issues
• May expose sensitive information in logs - use carefully

--help

What it does: Displays help information about available commands and options.

When to use: When you need a quick reference of available options.

Examples:

nism --help                          # Show main help
nism load --help                     # Help for specific command

--version

What it does: Displays the current version of the NewInstance Secret Manager CLI.

When to use: When you need to check which version you're running or for support purposes.

Examples:

nism --version                       # Show version

Parameter Interactions

Common Combinations

Basic Usage:

# Minimal command with environment variables set
export NEW_INSTANCE_APP_ID="app_123456"
export NEW_INSTANCE_API_KEY="key_abcdef"
export NEW_INSTANCE_APP_SECRET="secret_xyz789"
nism

Development Workflow:

# Load development environment with .env file creation (auto-add-to-profile is enabled by default)
nism --environment="development" --create-env=".env"

Production Deployment:

# Load production environment to file for deployment
nism --environment="production" --output=".env.production" --format="dotenv" --silent="true"

Multi-Project Setup:

# Set up named environment sets for different projects (auto-add-to-profile is enabled by default)
nism --env-set-name="project1"
nism --env-set-name="project2"

CI/CD Pipeline:

# Automated environment loading without prompts
nism --environment="production" --output=".env" --silent="true" --prompt-for-elevation="false"

Troubleshooting:

# Debug mode with detailed logging and environment variable verification
nism --debug="true" --silent="false"

Examples

Load Production Environment Variables

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --environment="production"

Write to .env File

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --output=".env.local"

Create .env File in Current Directory

# Create .env file in current directory
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --create-env=".env"

# Create custom-named .env file
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --create-env="development.env"

# Create .env file in subdirectory (creates directory if needed)
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --create-env="config/app.env"

Output as JSON

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --output="env.json" --format="json"

Using Environment Variables

Instead of passing sensitive information as command-line arguments, you can set environment variables:

# Set environment variables
export NEW_INSTANCE_APP_ID="app_123456"
export NEW_INSTANCE_API_KEY="key_abcdef"
export NEW_INSTANCE_APP_SECRET="secret_xyz789"

# Run the command without specifying the sensitive parameters
nism --environment="production" --output=".env.production"

This approach is more secure, especially in CI/CD environments, as it avoids exposing sensitive information in process listings or command history.

Silent Mode

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --silent="true"

Shell Integration

Automatic Shell Integration (New!)

The latest version of NISM provides seamless shell integration that automatically makes environment variables available in your current shell session:

# Run the setup command once to configure shell integration
npx nism setup

# Then use NISM with any command
npx nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --debug="true"

After running the command, the environment variables will be immediately available in your current shell:

# Access the variables directly
echo $DATABASE_URL

This works across all major shells and platforms:

• Bash - Full support with BASH_SOURCE detection
• Zsh - Full support with ZSH_EVAL_CONTEXT detection
• Ksh - Korn Shell (ksh88/ksh93) with .sh.file detection
• Fish - Fish Shell with native set -gx syntax and Fish-specific conditionals
• Dash - Debian Almquist Shell with POSIX compliance
• POSIX - Universal POSIX-compliant shell script for maximum compatibility
• PowerShell and CMD on Windows (via POSIX compatibility layer)

Multi-Shell Architecture: The CLI automatically creates shell-specific integration files optimized for each shell type:

• shell-integration.sh - Universal POSIX-compatible version
• shell-integration-bash.sh - Bash-optimized version
• shell-integration-zsh.zsh - Zsh-optimized version
• shell-integration-ksh.ksh - Korn Shell version
• shell-integration-fish.fish - Fish Shell with native syntax
• shell-integration-dash.sh - Dash/POSIX minimal version

Performance Note: All shell integration scripts contain directly embedded environment variable export statements, eliminating the need for JSON parsing or Node.js runtime dependencies during shell script execution. Scripts are automatically regenerated with updated values each time the CLI runs.

Shell-Specific Usage:

# Bash/Zsh users
source ~/.nism/shell-integration.sh

# Fish users
source ~/.nism/shell-integration-fish.fish

# Korn Shell users
. ~/.nism/shell-integration-ksh.ksh

# Dash users (minimal POSIX)
. ~/.nism/shell-integration-dash.sh

Manual Shell Integration (Legacy)

You can also use the --shell option to generate a shell script that you can manually source:

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --shell="true"

This will generate a shell script (env.sh by default) that you can source to export the variables to your shell:

Unix-like Systems (Linux, macOS)

# Source the generated script
source env.sh

# Now you can access the variables in your shell
echo $DATABASE_URL

Windows Command Prompt

:: Call the generated script
call env.sh

:: Now you can access the variables in your shell
echo %DATABASE_URL%

Windows PowerShell

# Source the generated script
. .\env.sh

# Now you can access the variables in your shell
echo $env:DATABASE_URL

Both approaches ensure that the environment variables are properly exported to the parent shell process, making them accessible to other commands and scripts.

System-Level Environment Variables

The Secret Key Manager SDK can set environment variables at the system level, making them accessible to all applications and processes without requiring manual sourcing of scripts. This feature attempts to set variables using the most appropriate method for your operating system:

# Set environment variables at the system level
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789"

How It Works

The SDK uses different approaches based on your operating system:

Windows:

1. Attempts to set system-level environment variables using the Windows Registry
2. Falls back to user-level environment variables if system-level fails
3. Creates startup scripts if neither system nor user-level setting succeeds

Unix-like Systems (Linux, macOS):

1. Attempts to create a script in /etc/profile.d/ for system-wide variables
2. Falls back to modifying user profile files (.bashrc, .zshrc, .profile)
3. Creates a startup script if neither system nor profile modification succeeds

Privilege Requirements

Setting system-level environment variables often requires administrative privileges:

• On Windows, the SDK will prompt for elevation (UAC) if needed
• On Unix-like systems, the SDK will use sudo if needed

You can control this behavior with the --prompt-for-elevation="true" and --prompt-for-elevation="false" options.

Accessing Variables in Different Contexts

After setting system-level environment variables, they will be accessible E.g:

In new terminal windows:

# Bash/Zsh
echo $DATABASE_URL

# Windows Command Prompt
echo %DATABASE_URL%

# PowerShell
echo $env:DATABASE_URL

In applications: Environment variables will be accessible to all applications launched after they are set. Existing applications may need to be restarted.

In different programming languages:

# Python
import os
print(os.environ['DATABASE_URL'])

// Java
System.out.println(System.getenv("DATABASE_URL"));

# Ruby
puts ENV['DATABASE_URL']

Technical Limitations

There are some inherent limitations to setting system-level environment variables:

1. Existing Processes: Environment variables cannot be modified for already-running processes
2. Session Scope: Some changes may require logging out and back in to take full effect
3. Security Restrictions: Modern operating systems restrict environment variable modifications for security reasons

The SDK will provide clear warnings and fallback mechanisms when these limitations are encountered.

Environment Variable Bridge

The Environment Variable Bridge provides a way to share environment variables across terminal sessions without requiring administrative privileges. It's the recommended approach for most users as it provides the best balance of convenience and security.

# Use the Environment Variable Bridge
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --bridge="true"

How It Works

The Environment Variable Bridge stores environment variables in a central location (~/.nism by default) and provides shell integration scripts that can be sourced to load the variables in any terminal session.

1. Variables are stored in JSON format for persistence
2. Shell integration scripts are generated for different shells (Bash, Zsh, Fish, CMD, PowerShell)
3. Activation commands are provided to load the variables in new terminal sessions

Accessing Variables in Different Terminals

After setting variables with the Environment Variable Bridge, you can access them in new terminal sessions by running the activation command:

Bash/Zsh:

source ~/.nism/default/activate.sh

Fish:

source ~/.nism/default/activate.fish

Windows Command Prompt:

call %USERPROFILE%\.nism\default\activate.bat

PowerShell:

. $HOME\.nism\default\activate.ps1

Automatic Profile Integration

For even more convenience, you can automatically add the activation commands to your shell profile files:

nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --auto-add-to-profile="true"

This will add the appropriate activation command to your shell profile file (.bashrc, .zshrc, etc.), ensuring that the environment variables are automatically loaded in every new terminal session.

Named Environment Sets

You can create multiple named sets of environment variables for different projects or environments:

# Create a 'project1' environment set
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --env-set-name="project1"

# Create a 'project2' environment set
nism --appId="app_789012" --apiKey="key_defghi" --appSecret="secret_345678" --env-set-name="project2"

Then activate the specific set you need:

# Activate project1 environment
source ~/.nism/project1/activate.sh

# Activate project2 environment
source ~/.nism/project2/activate.sh

IDE Integration

You can create .env files for IDE and development tool integration using the --create-env option:

# Create .env file in current directory
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --create-env=".env"

# Create custom-named .env file for specific environments
nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --create-env="development.env"

Many IDEs and frameworks (VS Code, JetBrains IDEs, Next.js, etc.) automatically load variables from .env files in the project root.

Advantages Over System-Level Variables

The Environment Variable Bridge offers several advantages over system-level environment variables:

1. No Administrative Privileges Required: Works without needing system passwords
2. Cross-Terminal Accessibility: Variables can be accessed from any terminal session
3. Optional IDE Integration: Create .env files on-demand using --create-env
4. Named Environment Sets: Support for multiple projects or environments
5. Cross-Platform Consistency: Works the same way across all operating systems

Programmatic Usage

You can also use the library programmatically in your Node.js applications:

const { loadEnvironmentVariables, EnvVarEnvironment, OutputFormat } = require('newinstance-secret-manager');

async function loadEnv() {
  try {
    // You can get credentials from environment variables or configuration
    const appId = process.env.NEW_INSTANCE_APP_ID || 'app_123456';
    const apiKey = process.env.NEW_INSTANCE_API_KEY || 'key_abcdef';
    const appSecret = process.env.NEW_INSTANCE_APP_SECRET || 'secret_xyz789';

    // Example 1: Load variables into process.env
    await loadEnvironmentVariables(
      appId,
      apiKey,
      appSecret,
      {
        environment: EnvVarEnvironment.Production,
        silent: true
      }
    );
    console.log('Environment variables loaded into process.env');

    // Example 2: Set system-level environment variables
    await loadEnvironmentVariables(
      appId,
      apiKey,
      appSecret,
      {
        environment: EnvVarEnvironment.Production,
        systemLevel: true,
        promptForElevation: true,
        modifyProfileFiles: true,
        createStartupScript: true,
        showWarnings: true,
        silent: false
      }
    );
    console.log('System-level environment variables set');

    // Example 3: Generate a .env file
    await loadEnvironmentVariables(
      appId,
      apiKey,
      appSecret,
      {
        environment: EnvVarEnvironment.Production,
        output: '.env.production',
        format: OutputFormat.DotEnv,
        silent: true
      }
    );
    console.log('Environment variables written to .env.production');

    // Example 4: Generate a shell script for shell integration
    await loadEnvironmentVariables(
      appId,
      apiKey,
      appSecret,
      {
        environment: EnvVarEnvironment.Production,
        output: 'env.sh',
        format: OutputFormat.ShellScript,
        silent: true
      }
    );
    console.log('Shell script generated at env.sh');
    console.log('To use it, run: source env.sh');
  } catch (error) {
    console.error('Error loading environment variables:', error);
  }
}

async function loadEnvWithBridge() {
  try {
    // You can get credentials from environment variables or configuration
    const appId = process.env.NEW_INSTANCE_APP_ID || 'app_123456';
    const apiKey = process.env.NEW_INSTANCE_API_KEY || 'key_abcdef';
    const appSecret = process.env.NEW_INSTANCE_APP_SECRET || 'secret_xyz789';

    // Use the Environment Variable Bridge
    await loadEnvironmentVariables(
      appId,
      apiKey,
      appSecret,
      {
        environment: EnvVarEnvironment.Production,
        useBridge: true,
        bridgeStorageDir: path.join(os.homedir(), '.nism'),
        envSetName: 'myproject',
        autoAddToProfile: true,
        silent: false
      }
    );
    console.log('Environment variables set with the Environment Variable Bridge');
  } catch (error) {
    console.error('Error loading environment variables:', error);
  }
}

loadEnv();
// Or use the bridge
// loadEnvWithBridge();

Environment Variable Inheritance

The Secret Key Manager supports environment variable inheritance, allowing apps to inherit variables from other apps. This is useful for sharing common configuration across multiple applications.

When loading environment variables, the env-loader will automatically include inherited variables. If there are conflicts (variables with the same key), the app's own variables take precedence over inherited ones.

┌─────────────┐
│ Parent App  │
│             │
│ DB_HOST     │
│ DB_PORT     │
│ DB_USER     │
└─────┬───────┘
      │
      │ inherits
      │
      ▼
┌─────────────┐
│ Child App   │
│             │
│ DB_USER     │ (overrides parent's DB_USER)
│ API_KEY     │
└─────────────┘

Secure Inheritance with Envelope Encryption

The Secret Key Manager uses a secure envelope encryption model for environment variable inheritance. This model ensures that each app only needs its own app secret to decrypt any variables it has access to, including inherited variables.

const { loadEnvironmentVariables, EnvVarEnvironment } = require('newinstance-secret-manager');

async function loadEnv() {
  try {
    // Only the app's own secret is needed, even for inherited variables
    await loadEnvironmentVariables(
      'app_123456',
      'key_abcdef',
      'secret_xyz789',
      {
        environment: EnvVarEnvironment.Production
      }
    );
    console.log('Environment variables loaded successfully');
  } catch (error) {
    console.error('Error loading environment variables:', error);
  }
}

When using the command-line tool, simply provide your app's credentials:

# Set the target app credentials
export NEW_INSTANCE_APP_ID="app_123456"
export NEW_INSTANCE_API_KEY="key_abcdef"
export NEW_INSTANCE_APP_SECRET="secret_xyz789"

# Run the command
nism

Troubleshooting

System-Level Environment Variables

Variables Not Available in New Terminal Windows

If environment variables are not available in new terminal windows after setting them at the system level:

1. Check the method used: The SDK will display the method used to set the variables (system, user, profile, startup, or process). If it falls back to 'process', the variables will only be available in the current process.

2. Log out and back in: Some system-level changes require logging out and back in to take effect.

3. Check permissions: Setting system-level variables often requires administrative privileges. Try running the command with administrator/root privileges.

4. Check for errors: Look for error messages in the SDK output that might indicate why system-level setting failed.

5. Use the startup script: If the SDK created a startup script, source it manually:

   # Unix-like systems
   source ~/nism-env.sh
   
   # Windows Command Prompt
   call %USERPROFILE%\nism-env.bat
   
   # Windows PowerShell
   . $HOME\nism-env.ps1

Permission Denied Errors

If you encounter permission denied errors:

1. On Windows: Run the command prompt or PowerShell as Administrator.

2. On Unix-like systems: Use sudo:

   sudo nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789"

3. Disable elevation prompts: If you don't have administrative privileges, disable elevation prompts:

   nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --prompt-for-elevation="false"

Variables Not Available to Specific Applications

If variables are available in the terminal but not in specific applications:

1. Restart the application: Applications only see environment variables that were set before they started.

2. Check application permissions: Some applications run with different permissions and may not see user-level environment variables.

3. Use a .env file instead: Generate a .env file and configure your application to load it:

   nism --appId="app_123456" --apiKey="key_abcdef" --appSecret="secret_xyz789" --output .env

Environment Variable Bridge

Variables Not Available in New Terminal Sessions

If environment variables set with the Environment Variable Bridge are not available in new terminal sessions:

1. Check the activation command: Make sure you're running the correct activation command for your shell:

   # Bash/Zsh
   source ~/.nism/default/activate.sh
   
   # Fish
   source ~/.nism/default/activate.fish
   
   # Windows Command Prompt
   call %USERPROFILE%\.nism\default\activate.bat
   
   # PowerShell
   . $HOME\.nism\default\activate.ps1

2. Check the environment set name: If you specified a custom environment set name, make sure you're using the correct name in the activation command:

   source ~/.nism/myproject/activate.sh

3. Check file permissions: Make sure the activation scripts have the correct permissions:

   chmod +x ~/.nism/default/activate.sh

4. Use automatic profile integration: For a more seamless experience, use the --auto-add-to-profile option to automatically add the activation command to your shell profile:

   nism --auto-add-to-profile="true"

Multiple Projects with Different Variables

If you're working on multiple projects that require different environment variables:

1. Use named environment sets: Create a separate environment set for each project:

   nism --env-set-name="project1" --appId="app_123456"
   nism --env-set-name="project2" --appId="app_789012"

2. Activate the specific set you need: Source the activation script for the project you're working on:

   source ~/.nism/project1/activate.sh

3. Use project-specific .env files: Create .env files directly in your project directories:

   cd ./project1
   nism --env-set-name="project1" --create-env=".env"

AWS Elastic Beanstalk Troubleshooting

Deployment Failures

If your Elastic Beanstalk deployment fails when loading environment variables:

1. Check deployment logs: View the deployment logs in the Elastic Beanstalk console:

   # Access logs via EB CLI
   eb logs
   
   # Or check specific log files
   eb ssh
   sudo tail -f /var/log/eb-engine.log
   sudo tail -f /var/log/eb-hooks.log

2. Verify NewInstance credentials: Ensure your credentials are correctly set in the Elastic Beanstalk environment:

   # Check environment variables in EB console or via CLI
   eb printenv

3. Test NISM installation: SSH into your instance and test NISM manually:

   eb ssh
   nism --version
   nism --appId="your_app_id" --apiKey="your_api_key" --appSecret="your_app_secret" --debug="true"

4. File System Permissions: Check that your deployment hooks have proper permissions:

   # In your .platform/hooks/prebuild/ scripts
   chmod +x /var/app/staging/.platform/hooks/prebuild/*.sh

Environment Variable Loading Issues

If environment variables are not being loaded correctly:

1. Check .env file creation: Verify that .env files are being created in the correct location:

   # Add debugging to your deployment hooks
   echo "Current directory: $(pwd)"
   echo "Files in current directory: $(ls -la)"
   echo "Contents of .env file:"
   cat .env || echo ".env file not found"

2. Verify environment variable availability: Test that variables are accessible to your application:

   // Add to your application startup
   console.log('Environment variables loaded:');
   console.log('DATABASE_URL:', process.env.DATABASE_URL ? 'Set' : 'Not set');
   console.log('API_KEY:', process.env.API_KEY ? 'Set' : 'Not set');

3. Check timing issues: Ensure environment variables are loaded before your application starts:

   # .ebextensions/05-timing.config
   commands:
     01_load_secrets_early:
       command: |
         nism --create-env="/opt/elasticbeanstalk/deployment/.env" --silent="true"
       env:
         NEW_INSTANCE_APP_ID: $NEW_INSTANCE_APP_ID
         NEW_INSTANCE_API_KEY: $NEW_INSTANCE_API_KEY
         NEW_INSTANCE_APP_SECRET: $NEW_INSTANCE_APP_SECRET

Network and Connectivity Issues

If you experience network issues when connecting to NewInstance service:

1. Check VPC configuration: If your Elastic Beanstalk environment is in a private VPC:

   # Ensure your VPC has internet access via NAT Gateway or Internet Gateway
   # Check security group rules allow outbound HTTPS traffic

2. Test connectivity: SSH into your instance and test connectivity:

   eb ssh
   curl -I https://api.newinstance.com
   nslookup api.newinstance.com

3. Configure proxy settings: If behind a corporate proxy:

   # Set proxy environment variables in your deployment
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080

Performance and Timeout Issues

If you experience slow deployments or timeouts:

1. Increase deployment timeout: Configure longer timeouts in your Elastic Beanstalk settings:

   # .ebextensions/06-timeouts.config
   option_settings:
     aws:elasticbeanstalk:command:
       Timeout: 900
       IgnoreHealthCheck: true

2. Optimize NISM calls: Use silent mode and caching to improve performance:

   # Cache environment variables to reduce service calls
   nism --silent="true" --output="/tmp/cached-env" --format="shell"
   source /tmp/cached-env

3. Parallel processing: For multiple environment sets, consider parallel loading:

   # Load multiple environment sets in parallel
   nism --env-set-name="app1" --create-env=".env.app1" --silent="true" &
   nism --env-set-name="app2" --create-env=".env.app2" --silent="true" &
   wait

Docker Container Issues

For Docker-based Elastic Beanstalk deployments:

1. Container startup failures: Check that your entrypoint script is executable:

   # Ensure proper permissions in Dockerfile
   COPY docker-entrypoint.sh /usr/local/bin/
   RUN chmod +x /usr/local/bin/docker-entrypoint.sh

2. Environment variable inheritance: Ensure environment variables are passed to the container:

   # Dockerrun.aws.json
   {
     "AWSEBDockerrunVersion": "1",
     "Image": {
       "Name": "your-image:latest"
     },
     "Ports": [
       {
         "ContainerPort": "3000"
       }
     ],
     "Environment": [
       {
         "Name": "NEW_INSTANCE_APP_ID",
         "Value": "app_123456"
       }
     ]
   }

3. Debug container issues: Add debugging to your entrypoint script:

   #!/bin/sh
   set -e
   
   echo "Container starting..."
   echo "Environment variables:"
   env | grep NEW_INSTANCE || echo "No NEW_INSTANCE variables found"
   
   # Test NISM installation
   which nism || echo "NISM not found in PATH"
   nism --version || echo "NISM version check failed"
   
   # Continue with normal startup
   exec "$@"

Cross-Platform Compatibility

The NewInstance Secret Manager is designed to work consistently across all major operating systems:

Environment Variables

When setting environment variables in the current process:

• Linux/macOS: Variables are immediately available to the current process but not to other processes
• Windows: Variables are immediately available to the current process but not to other processes

For system-wide availability:

Linux/macOS

# Add to ~/.bashrc or ~/.zshrc for persistence
export NEW_INSTANCE_APP_ID="app_123456"
export NEW_INSTANCE_API_KEY="key_abcdef"
export NEW_INSTANCE_APP_SECRET="secret_xyz789"

Windows (Command Prompt)

:: Set for current session
set NEW_INSTANCE_APP_ID=app_123456
set NEW_INSTANCE_API_KEY=key_abcdef
set NEW_INSTANCE_APP_SECRET=secret_xyz789

:: Set permanently (requires admin privileges)
setx NEW_INSTANCE_APP_ID "app_123456" /M
setx NEW_INSTANCE_API_KEY "key_abcdef" /M
setx NEW_INSTANCE_APP_SECRET "secret_xyz789" /M

Windows (PowerShell)

# Set for current session
$env:NEW_INSTANCE_APP_ID = "app_123456"
$env:NEW_INSTANCE_API_KEY = "key_abcdef"
$env:NEW_INSTANCE_APP_SECRET = "secret_xyz789"

# Set permanently (requires admin privileges)
[Environment]::SetEnvironmentVariable("NEW_INSTANCE_APP_ID", "app_123456", "Machine")
[Environment]::SetEnvironmentVariable("NEW_INSTANCE_API_KEY", "key_abcdef", "Machine")
[Environment]::SetEnvironmentVariable("NEW_INSTANCE_APP_SECRET", "secret_xyz789", "Machine")

Child Processes

When using the utility to set environment variables:

• Variables set in process.env are automatically inherited by child processes spawned from the current Node.js process
• For other processes, use the --output option to write to a file, then source that file in your scripts

# Generate .env file
nism --output=".env"

# Source the file in bash
source .env

# Or in Windows command prompt
type .env > temp.bat && temp.bat && del temp.bat

CI/CD Integration

GitHub Actions

name: Deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Load environment variables
        env:
          NEW_INSTANCE_APP_ID: ${{ secrets.APP_ID }}
          NEW_INSTANCE_API_KEY: ${{ secrets.API_KEY }}
          NEW_INSTANCE_APP_SECRET: ${{ secrets.APP_SECRET }}
        run: |
          npx nism \
            --environment="production" \
            --output=".env.production"

      - name: Deploy application
        run: npm run deploy

CircleCI

version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout
      - run:
          name: Load environment variables
          environment:
            NEW_INSTANCE_APP_ID: ${APP_ID}
            NEW_INSTANCE_API_KEY: ${API_KEY}
            NEW_INSTANCE_APP_SECRET: ${APP_SECRET}
          command: |
            npx nism \
              --environment="production" \
              --output=".env.production"
      - run:
          name: Deploy application
          command: npm run deploy

Jenkins

pipeline {
    agent {
        docker {
            image 'node:18'
        }
    }
    stages {
        stage('Load Environment Variables') {
            environment {
                NEW_INSTANCE_APP_ID = credentials('app-id')
                NEW_INSTANCE_API_KEY = credentials('api-key')
                NEW_INSTANCE_APP_SECRET = credentials('app-secret')
            }
            steps {
                sh '''
                npx nism \
                  --environment="production" \
                  --output=".env.production"
                '''
            }
        }
        stage('Deploy') {
            steps {
                sh 'npm run deploy'
            }
        }
    }
}

GitLab CI

stages:
  - build
  - deploy

variables:
  NODE_VERSION: "18"
  # Define these in GitLab CI/CD Settings → Variables (protected and masked)
  # NEW_INSTANCE_APP_ID: "app_123456"
  # NEW_INSTANCE_API_KEY: "key_abcdef"
  # NEW_INSTANCE_APP_SECRET: "secret_xyz789"

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    # Load environment variables using environment variables from GitLab CI/CD settings
    - |
      npx nism \
        --environment="production" \
        --output=".env.production"
    - npm run build
  artifacts:
    paths:
      - dist/
      - .env.production
  cache:
    paths:
      - node_modules/
  only:
    - main

deploy:
  stage: deploy
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run deploy
  dependencies:
    - build
  only:
    - main

AWS CodePipeline (buildspec.yml)

version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 18
    commands:
      - npm ci

  pre_build:
    commands:
      # Load environment variables using environment variables from CodeBuild environment
      # Define NEW_INSTANCE_APP_ID, NEW_INSTANCE_API_KEY, and NEW_INSTANCE_APP_SECRET
      # in CodeBuild project environment variables (mark them as PARAMETER_STORE for security)
      - |
        npx nism \
          --environment="production" \
          --output=".env.production"

  build:
    commands:
      - npm run build

  post_build:
    commands:
      - npm run deploy

artifacts:
  files:
    - dist/**/*
    - .env.production
    - appspec.yml
  discard-paths: no

cache:
  paths:
    - node_modules/**/*

AWS Elastic Beanstalk

AWS Elastic Beanstalk provides multiple approaches for integrating with NewInstance Secret Manager, depending on your deployment strategy and security requirements.

Method 1: Environment Variables in Elastic Beanstalk Configuration

Store your NewInstance credentials as Elastic Beanstalk environment variables and use them during deployment:

1. Set Environment Variables in Elastic Beanstalk Console:

NEW_INSTANCE_APP_ID = app_123456
NEW_INSTANCE_API_KEY = key_abcdef
NEW_INSTANCE_APP_SECRET = secret_xyz789

2. Create .ebextensions/01-environment-setup.config:

commands:
  01_install_nism:
    command: "npm install -g newinstance-secret-manager"
    ignoreErrors: false

  02_load_environment_variables:
    command: |
      nism \
        --environment="production" \
        --output="/opt/elasticbeanstalk/deployment/env" \
        --format="shell" \
        --silent="true"
    env:
      NEW_INSTANCE_APP_ID: $NEW_INSTANCE_APP_ID
      NEW_INSTANCE_API_KEY: $NEW_INSTANCE_API_KEY
      NEW_INSTANCE_APP_SECRET: $NEW_INSTANCE_APP_SECRET

  03_source_environment:
    command: "source /opt/elasticbeanstalk/deployment/env"

Method 2: Pre-deployment Hook with .env File Creation

Use Elastic Beanstalk deployment hooks to create .env files before your application starts:

Create .platform/hooks/prebuild/load-secrets.sh:

#!/bin/bash
set -e

echo "Loading environment variables from NewInstance Secret Manager..."

# Install NISM if not already installed
if ! command -v nism &> /dev/null; then
    npm install -g newinstance-secret-manager
fi

# Load environment variables and create .env file
nism \
  --environment="production" \
  --create-env=".env" \
  --silent="true"

echo "Environment variables loaded successfully"

Make the script executable in .platform/hooks/prebuild/make-executable.sh:

#!/bin/bash
chmod +x /var/app/staging/.platform/hooks/prebuild/load-secrets.sh

Method 3: Application-Level Integration

Integrate NewInstance Secret Manager directly into your application startup:

For Node.js applications, add to your main application file:

const { loadEnvironmentVariables, EnvVarEnvironment } = require('newinstance-secret-manager');

async function initializeApp() {
  try {
    // Load environment variables on application startup
    await loadEnvironmentVariables(
      process.env.NEW_INSTANCE_APP_ID,
      process.env.NEW_INSTANCE_API_KEY,
      process.env.NEW_INSTANCE_APP_SECRET,
      {
        environment: EnvVarEnvironment.Production,
        silent: true
      }
    );

    console.log('Environment variables loaded from NewInstance Secret Manager');

    // Start your application
    startServer();
  } catch (error) {
    console.error('Failed to load environment variables:', error);
    process.exit(1);
  }
}

initializeApp();

Method 4: Docker-based Deployment

For containerized applications deployed to Elastic Beanstalk:

Create Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies including NISM
RUN npm ci --only=production && \
    npm install -g newinstance-secret-manager

# Copy application code
COPY . .

# Create startup script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

EXPOSE 3000

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["npm", "start"]

Create docker-entrypoint.sh:

#!/bin/sh
set -e

echo "Loading environment variables from NewInstance Secret Manager..."

# Load environment variables
nism \
  --environment="${NODE_ENV:-production}" \
  --create-env=".env" \
  --silent="true"

echo "Environment variables loaded successfully"

# Execute the main command
exec "$@"

Method 5: AWS Systems Manager Parameter Store Integration

Combine NewInstance Secret Manager with AWS Systems Manager for enhanced security:

1. Store NewInstance credentials in Parameter Store:

aws ssm put-parameter \
  --name "/myapp/newinstance/app-id" \
  --value "app_123456" \
  --type "String"

aws ssm put-parameter \
  --name "/myapp/newinstance/api-key" \
  --value "key_abcdef" \
  --type "SecureString"

aws ssm put-parameter \
  --name "/myapp/newinstance/app-secret" \
  --value "secret_xyz789" \
  --type "SecureString"

2. Create .ebextensions/02-parameter-store.config:

commands:
  01_install_aws_cli:
    command: "pip install awscli"

  02_load_from_parameter_store:
    command: |
      export NEW_INSTANCE_APP_ID=$(aws ssm get-parameter --name "/myapp/newinstance/app-id" --query "Parameter.Value" --output text)
      export NEW_INSTANCE_API_KEY=$(aws ssm get-parameter --name "/myapp/newinstance/api-key" --with-decryption --query "Parameter.Value" --output text)
      export NEW_INSTANCE_APP_SECRET=$(aws ssm get-parameter --name "/myapp/newinstance/app-secret" --with-decryption --query "Parameter.Value" --output text)

      nism \
        --environment="production" \
        --create-env="/opt/elasticbeanstalk/deployment/.env" \
        --silent="true"

Best Practices for Elastic Beanstalk Integration

Security Considerations:

1. Use IAM Roles: Assign appropriate IAM roles to your Elastic Beanstalk environment for Parameter Store access
2. Environment Separation: Use different NewInstance environments for development, staging, and production
3. Credential Rotation: Regularly rotate your NewInstance API keys and app secrets
4. Least Privilege: Grant minimal required permissions to your Elastic Beanstalk service role

Performance Optimization:

1. Caching: Cache environment variables to reduce NewInstance service calls
2. Silent Mode: Always use --silent="true" in production deployments
3. Error Handling: Implement proper error handling for failed secret retrieval
4. Timeout Configuration: Set appropriate timeouts for NewInstance service calls

Deployment Strategy:

# .ebextensions/03-deployment-strategy.config
option_settings:
  aws:elasticbeanstalk:command:
    DeploymentPolicy: RollingWithAdditionalBatch
    BatchSizeType: Percentage
    BatchSize: 30
    Timeout: 600
  aws:elasticbeanstalk:application:environment:
    NODE_ENV: production
    NISM_TIMEOUT: 30000

Health Checks:

# .ebextensions/04-health-checks.config
files:
  "/opt/elasticbeanstalk/tasks/bundlelogs.d/01-nism-logs.conf":
    mode: "000644"
    owner: root
    group: root
    content: |
      /var/log/nism.log

Troubleshooting

Common Errors

Authentication Failures

Error: Invalid API key or app ID. Please check your credentials.

Make sure your API key and app ID are correct. The API key should have access to the specified app.

Network Errors

Error: Failed to connect to server: Request timed out after 10000ms. Check your internet connection.

Check your internet connection and make sure the NewInstance service is accessible.

Decryption Errors

Error: Failed to decrypt environment variable API_KEY: Invalid key length

Make sure your App Secret is correct. If you've regenerated your App Secret, you'll need to use the new one.

Rate Limiting Issues

Error: Rate limit exceeded. Try again after 2023-07-01T12:00:00.000Z (Unix timestamp: 1625140800)

You've exceeded the rate limit for NewInstance service requests. Wait until the specified time before trying again.

Missing Parameters or Environment Variables

Error: Missing required parameter: appId. Provide it via --appId command line option or NEW_INSTANCE_APP_ID environment variable.

Make sure you've provided all required parameters either via command-line arguments or environment variables.

File System Errors

Error: Failed to write to file /path/to/file: Permission denied

Make sure you have write permissions for the specified output file path.

Security Best Practices

1. Never store your App Secret in code or version control

   • Use environment variables or a secure secret management solution

2. Prefer environment variables over command-line arguments for sensitive information

   # Set environment variables
   export NEW_INSTANCE_APP_ID="app_123456"
   export NEW_INSTANCE_API_KEY="key_abcdef"
   export NEW_INSTANCE_APP_SECRET="secret_xyz789"
   
   # Run without exposing secrets in command line
   nism --environment="production"

3. Use secure environment variable storage in CI/CD systems

   • GitHub Actions: Use repository secrets
   • CircleCI: Use context or project environment variables
   • Jenkins: Use credentials binding
   • GitLab CI: Use CI/CD variables (Settings → CI/CD → Variables)
   • AWS CodePipeline: Use environment variables in CodeBuild project settings

4. Restrict API key permissions

   • Create API keys with the minimum required permissions

5. Regularly rotate API keys

   • Periodically generate new API keys and revoke old ones

6. Use a dedicated CI/CD service account

   • Don't use personal API keys in CI/CD pipelines

License

MIT