CLI Reference

Complete reference for all Shuttle CLI commands and options for Python projects.

Overview

The Shuttle CLI for Python is your primary interface for developing, deploying, and managing applications on the Shuttle platform. This reference provides comprehensive documentation for all commands and options.

Installation

It is recommended to use uv for dependency management and running the Shuttle CLI.

uv venv
source .venv/bin/activate
uv add shuttle-cobra

Once installed, you can invoke the Shuttle CLI using uv run -m shuttle. If your virtual environment is activated, you can also run commands directly using shuttle. For example:

uv run -m shuttle deploy
# OR
shuttle deploy

Global Options

These options are common to many command-line interfaces and may be supported by the underlying Python click framework, but are not explicitly defined or handled by the shuttle Python application's __main__.py for all cases.

Option	Description
--debug	Turn on tracing output for Shuttle libraries (WARNING: can print sensitive data)

Commands Reference

Project Management

Deployment

shuttle deploy

Provision, build, and deploy the application.

uv run -m shuttle deploy [PATH]
# OR
shuttle deploy [PATH]

Arguments:

• [PATH] - The path to your Shuttle project's root directory (defaults to current directory).

Examples:

uv run -m shuttle deploy # Deploy the project in the current directory
shuttle deploy # Deploy the project in the current directory

uv run -m shuttle deploy my-project # Deploy a project located in 'my-project' directory
shuttle deploy my-project # Deploy a project located in 'my-project' directory

shuttle destroy

Destroy the deployed stack and all associated resources for a project.

uv run -m shuttle destroy [PATH]
# OR
shuttle destroy [PATH]

Arguments:

• [PATH] - The path to your Shuttle project's root directory (defaults to current directory).

Examples:

uv run -m shuttle destroy # Destroy the project in the current directory
shuttle destroy # Destroy the project in the current directory

uv run -m shuttle destroy my-project # Destroy a project located in 'my-project' directory
shuttle destroy my-project # Destroy a project located in 'my-project' directory

Local Development

shuttle run

Run your Shuttle project locally.

uv run -m shuttle run [PATH]
# OR
shuttle run [PATH]

Arguments:

• [PATH] - The path to your Shuttle project's root directory (defaults to current directory).

Examples:

uv run -m shuttle run # Run the project in the current directory locally
shuttle run # Run the project in the current directory locally

uv run -m shuttle run my-project # Run a project located in 'my-project' directory locally
shuttle run my-project # Run a project located in 'my-project' directory locally

Logs

shuttle logs

Show logs from the deployed application.

uv run -m shuttle logs [PATH]
# OR
shuttle logs [PATH]

Arguments:

• [PATH] - The path to your Shuttle project's root directory (defaults to current directory).

Examples:

uv run -m shuttle logs # View logs for the project in the current directory
shuttle logs # View logs for the project in the current directory

uv run -m shuttle logs my-project # View logs for a project located in 'my-project' directory
shuttle logs my-project # View logs for a project located in 'my-project' directory

Environment Variables

The Shuttle Cobra CLI primarily relies on AWS authentication configured in your environment.

Variable	Description
AWS_ACCESS_KEY_ID	Your AWS access key ID. Used for programmatic access to AWS.
AWS_SECRET_ACCESS_KEY	Your AWS secret access key. Used in conjunction with AWS_ACCESS_KEY_ID.
AWS_SESSION_TOKEN	(Optional) The session token for temporary AWS credentials.
AWS_PROFILE	The name of the AWS profile to use from your AWS credentials file (~/.aws/credentials).
LOCALSTACK_AUTH_TOKEN	Used for testing with LocalStack; typically not needed for standard deployments.

You can configure your AWS credentials using aws configure or aws configure sso via the AWS CLI.

Configuration Files

pyproject.toml (and project structure)

Shuttle Cobra projects are standard Python projects, typically managed with pyproject.toml. Your application code, including @shuttle_task.cron decorated functions, resides within your project's Python source files (e.g., main.py or src/my_project/task.py).

[project]
name = "my-shuttle-project"
version = "0.1.0"
dependencies = [
    "shuttle-cobra",
    # ... other dependencies
]

Common Workflows

First Deployment

uv venv
source .venv/bin/activate
uv add shuttle
# Add your Shuttle Cobra code and dependencies (e.g., shuttle-aws, shuttle-db)
uv run -m shuttle deploy  # Deploy to AWS infrastructure managed by Shuttle
# OR
shuttle deploy
uv run -m shuttle run     # Test locally against provisioned infrastructure
# OR
shuttle run

Development Cycle

uv run -m shuttle deploy  # Deploy changes
# OR
shuttle deploy
uv run -m shuttle run     # Develop locally against provisioned infrastructure
# OR
shuttle run
uv run -m shuttle logs    # Check deployment logs
# OR
shuttle logs

Project Management

# The Python CLI manages projects through their local paths.
# To remove a project and its deployed resources:
uv run -m shuttle destroy
# OR
shuttle destroy

Debugging

uv run -m shuttle logs                  # Check recent logs
# OR
shuttle logs
uv run -m shuttle deploy --debug        # Verbose deployment (if --debug is implemented)
# OR
shuttle deploy --debug

Troubleshooting

Common Issues

AWS Authentication issues:

• Ensure your AWS credentials are correctly configured via environment variables or ~/.aws/credentials.

• Use aws configure or aws configure sso.

Local development issues:

• Ensure you are in the correct virtual environment (source .venv/bin/activate).

• Verify that your project path is correct (e.g., . for the current directory).

• Check for FileNotFoundError if main.py or __main__.py is missing in your project root.

Deployment issues:

• Check uv run -m shuttle logs for build or deployment errors.

• Ensure all Python dependencies are specified in pyproject.toml and installed (uv add shuttle or uv sync as appropriate).

Getting Help

uv run -m shuttle --help                   # General help
# OR
shuttle --help
uv run -m shuttle <command> --help        # Command-specific help (if supported by click)
# OR
shuttle <command> --help

For additional support:

• Discord Community

• GitHub Issues

• Documentation