Skip to main content

CLI Reference

deployless init​

Initializes a new deployless project with an interactive wizard.

deployless init             # Creates only deployless.yaml
deployless init --app       # Also creates app/, run.py, and .gitignore

Prompts for project name, stage, and runtime (with sensible defaults). The --app flag scaffolds the full project structure.

deployless build​

Generates template.yaml and builds the .dist/ packages.

deployless build
deployless build --stage prod            # Overrides the stage
deployless build -o infra/template.yaml  # Template output path
deployless build --dry-run               # Validates without writing files
deployless build --verbose               # Detailed output

deployless validate​

Validates the project without generating any files. Equivalent to build --dry-run but with cleaner output.

deployless validate
deployless validate --stage prod
deployless validate --check-existing   # Verifies existing=True resources exist in AWS
deployless validate --verbose

deployless check​

Runs pre-flight checks before deploying: validates env vars, verifies SAM CLI is installed, checks AWS credentials, and verifies existing=True resources.

deployless check
deployless check --stage prod
deployless check --verbose

deployless deploy​

Chains check + build + sam build + sam deploy. Requires the AWS SAM CLI.

If samconfig.toml does not exist (first deployment), --guided is added automatically.

deployless deploy
deployless deploy --stage prod
deployless deploy --guided          # Force wizard mode
deployless deploy --push-secrets    # Push SECRET_ vars to SSM before deploying
deployless deploy --verbose

The --stage flag​

The --stage flag overrides the stage value in deployless.yaml without editing the file. It affects:

  • API Gateway StageName — the URL prefix (/dev/, /prod/)
  • APP_STAGE env var — injected into all Lambda functions
  • samconfig.toml — the stack prefix for SAM

Useful in CI/CD:

# GitHub Actions — same deployless.yaml, different stage per branch
- run: deployless deploy --stage ${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}

deployless clean​

Removes generated files (.dist/ and template.yaml).

deployless clean
deployless clean -o infra/template.yaml  # If you used a different output path

deployless info​

Shows a summary of the detected project.

deployless info

Example output:

Project  : my-ums-api
Provider : aws
Stage    : dev
Runtime  : python3.13

Features (3):
  - auth    (app/features/auth/routes.py)
  - tenant  (app/features/tenant/routes.py)
  - user    (app/features/user/routes.py)

deployless secrets push​

Pushes the SECRET_* variables from the .env file to AWS SSM Parameter Store.

deployless secrets push
deployless secrets push --stage prod
deployless secrets push --env-file .env.prod
deployless secrets push --verbose

Process:

  1. Reads the .env file (from deployless.yaml or --env-file)
  2. Filters variables with the SECRET_ prefix
  3. Creates/updates SSM parameters: /{app_name}/{VAR_NAME} (type String)
note

deployless build does not push secrets automatically. Use deployless secrets push explicitly, or pass --push-secrets to deployless deploy.

deployless secrets sync​

Push + removes orphaned parameters in SSM. Keeps SSM in sync when secrets are removed from the .env.

deployless secrets sync
deployless secrets sync --stage prod
deployless secrets sync --env-file .env.prod
deployless secrets sync --yes              # Auto-confirms deletion
deployless secrets sync --verbose

Behavior:

  1. Pushes all SECRET_* variables (same as secrets push)
  2. Lists existing parameters under /{app_name}/ in SSM
  3. Detects parameters no longer in the .env
  4. Asks for confirmation before deleting (unless --yes)