CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-localstack-core

The core library and runtime of LocalStack - a comprehensive AWS cloud emulator for local development and testing.

—

Pending
Overview
Eval results
Files

cli-commands.mddocs/

CLI Commands

LocalStack provides a comprehensive command-line interface for managing the LocalStack runtime, configuration, services, and package management. All commands are accessed through the main localstack CLI entry point.

Capabilities

Lifecycle Management

Core commands for starting, stopping, and managing the LocalStack runtime.

def main() -> None:
    """
    Main CLI entry point. Sets LOCALSTACK_CLI=1 environment variable
    and processes --profile argument before configuration loading.
    
    Location: localstack.cli.main.main()
    Entry point: /bin/localstack
    """

Start Command

Start LocalStack runtime with extensive configuration options.

localstack start [OPTIONS]

# Core options:
--docker                    # Start in Docker container (default)
--host                     # Start directly on host system
--no-banner               # Disable LocalStack startup banner
-d, --detached            # Start in background mode

# Docker configuration:
--network NETWORK         # Use custom Docker network
-e, --env KEY=VALUE       # Set environment variables
-p, --publish PORT        # Port mappings (host:container)
-v, --volume PATH         # Volume mounts (host:container)
--host-dns               # Expose DNS server to host system

# Stack selection:
-s, --stack STACK        # Use specific stack (e.g., localstack:4.5, snowflake)

Usage examples:

# Basic start in Docker
localstack start

# Start with custom environment and ports  
localstack start -e DEBUG=1 -e SERVICES=s3,lambda -p 4566:4566

# Start with custom network and volumes
localstack start --network my-network -v /tmp/localstack:/var/lib/localstack

# Start in detached mode with specific stack
localstack start -d -s localstack:4.5

Stop Command

Stop the LocalStack runtime.

localstack stop

# Stops container named by MAIN_CONTAINER_NAME (default: localstack-main)

Restart Command

Restart LocalStack runtime within the container without stopping the container itself.

localstack restart

Logs Command

Display and follow LocalStack logs.

localstack logs [OPTIONS]

-f, --follow             # Follow log output (like tail -f)
-n, --tail N            # Show last N lines of logs

Usage examples:

# Show recent logs
localstack logs -n 100

# Follow logs in real-time
localstack logs -f

Wait Command

Wait for LocalStack to be ready and healthy.

localstack wait [OPTIONS]

-t, --timeout N         # Timeout in seconds (default: 60)

SSH Command

Get an interactive shell inside the LocalStack container.

localstack ssh

# Opens shell in running LocalStack container for debugging

Status Commands

Commands for checking LocalStack and service status.

Status Command

Query LocalStack operational status.

localstack status [SUBCOMMAND]

# Defaults to 'docker' subcommand if no subcommand specified

Docker Status

Check Docker container and runtime status.

localstack status docker [OPTIONS]

-f, --format FORMAT     # Output format (table, plain, dict, json)

Services Status

Check health status of individual AWS services.

localstack status services [OPTIONS]

-f, --format FORMAT     # Output format (table, plain, dict, json)

Response format example:

{
  "services": {
    "s3": "running",
    "lambda": "running", 
    "dynamodb": "available",
    "sqs": "starting"
  }
}

Configuration Commands

Commands for viewing and validating LocalStack configuration.

Show Configuration

Display current LocalStack configuration with multiple output formats.

localstack config show [OPTIONS]

-f, --format FORMAT     # Output format: table, plain, dict, json

Output includes all environment variables, computed paths, and service settings.

Validate Configuration

Validate docker-compose configuration files.

localstack config validate [OPTIONS]

-f, --file FILE         # Path to compose file (default: docker-compose.yml)

Update Commands

Commands for updating LocalStack components and images.

Update All

Update both CLI and Docker images to latest versions.

localstack update all

Update CLI

Update LocalStack CLI package via pip.

localstack update localstack-cli

# Equivalent to: pip install --upgrade localstack-core

Update Docker Images

Pull latest LocalStack Docker images.

localstack update docker-images

# Updates: localstack/localstack, localstack/localstack-pro, etc.

Package Management (LPM)

LocalStack Package Manager for installing additional components and services.

List Packages

List available packages in the LocalStack package repository.

localstack lpm list [OPTIONS]

-v, --verbose           # Show detailed package information and versions

Install Packages

Install one or more packages with configuration options.

localstack lpm install PACKAGE [PACKAGE...] [OPTIONS]

--parallel N           # Number of parallel installers (default: 1)
--version VERSION      # Install specific package version  
--target TARGET        # Installation target directory

Usage examples:

# Install single package
localstack lpm install dynamodb-local

# Install multiple packages in parallel
localstack lpm install --parallel 3 opensearch elasticsearch redis

# Install specific version
localstack lpm install --version 2.0.1 kinesis-mock

Advanced Commands

Additional utility and integration commands.

Shell Completion

Generate shell completion scripts for bash, zsh, and fish.

localstack completion SHELL

# Supported shells: bash, zsh, fish

Setup examples:

# Bash completion
localstack completion bash > ~/.localstack-completion.bash
echo 'source ~/.localstack-completion.bash' >> ~/.bashrc

# Zsh completion  
localstack completion zsh > ~/.localstack-completion.zsh
echo 'source ~/.localstack-completion.zsh' >> ~/.zshrc

# Fish completion
localstack completion fish > ~/.config/fish/completions/localstack.fish

Plugin Commands

Dynamic command loading via the plugin system.

class LocalstackCliPlugin:
    """
    Base class for CLI plugins that can add custom commands.
    
    Namespace: localstack.plugins.cli
    """
    namespace: str = "localstack.plugins.cli"
    
    def attach(self, cli) -> None:
        """
        Attach custom commands to the LocalStack CLI.
        
        Args:
            cli: LocalStack CLI instance
        """

def load_cli_plugins(cli) -> None:
    """
    Discover and load all CLI plugins from the namespace.
    Called automatically during CLI initialization.
    """

Plugin commands are automatically discovered and loaded from the localstack.plugins.cli namespace, allowing extensions to add custom functionality to the CLI.

Environment Variables

Key environment variables that affect CLI behavior:

# CLI behavior
LOCALSTACK_CLI = "1"           # Set automatically when using CLI
CONFIG_PROFILE = "profile"     # Active configuration profile

# Container management  
MAIN_CONTAINER_NAME = "localstack-main"  # Default container name
MAIN_DOCKER_NETWORK = "bridge"           # Docker network for container

# Debugging and logging
DEBUG = "1"                    # Enable debug mode
LS_LOG = "info"               # Logging level (trace, debug, info, warn, error)

Exit Codes

Standard exit codes returned by CLI commands:

  • 0 - Success
  • 1 - General error (configuration, runtime error)
  • 2 - Command line usage error
  • 3 - Service startup failure
  • 130 - Interrupted by user (Ctrl+C)

Configuration Files

CLI respects configuration from multiple sources in order of precedence:

  1. Command line arguments
  2. Environment variables
  3. Profile files (~/.localstack/profiles/<profile_name>)
  4. Default configuration (~/.localstack/config)

Profile loading is handled automatically when --profile argument is provided and occurs before general configuration loading.

Install with Tessl CLI

npx tessl i tessl/pypi-localstack-core

docs

aws-services.md

cli-commands.md

configuration.md

index.md

plugins-extensions.md

utils-testing.md

tile.json