@azure/containerapps-cli

CLI for Azure Container Apps environments.

Status: beta (1.0.0-beta.1) Binary: aca

Install

npm install -g @azure/containerapps-cli

Prerequisites

1. Install Azure CLI: https://learn.microsoft.com/cli/azure/install-azure-cli
2. Run az login
3. Set defaults as needed:

set AZURE_SUBSCRIPTION_ID=<subscription-id>
set ACA_RESOURCE_GROUP=<resource-group>
set ACA_SANDBOX_GROUP=<sandbox-group>

Quick Start

# Show auth state
aca auth status

# Create a sandbox group
aca sandboxgroup create --name my-group --location westus2 -g my-rg

# Create a sandbox
aca sandbox create --group my-group --disk ubuntu --wait

# List sandboxes
aca sandbox list --group my-group

# Run a command
aca sandbox exec --group my-group --id <sandbox-id> -c "echo hello"

Global Options

• -s, --subscription <subscription> Azure subscription ID
• -g, --resource-group <resourceGroup> Default resource group
• --group <group> Default sandbox group
• -o, --output <format> Output format: table, json
• --verbose Enable verbose logging
• --debug Enable debug logging

Commands

Auth

aca auth status

Sandbox Groups

aca sandboxgroup create --name <name> --location <loc> [-g <rg>]
aca sandboxgroup list [-g <rg>]
aca sandboxgroup get --name <name> [-g <rg>]
aca sandboxgroup delete --name <name> [-g <rg>] [--yes]
aca sandboxgroup update --name <name> [-g <rg>] --identity <type>

Sandbox

aca sandbox create --group <group> [--disk <disk>] [--snapshot <snapshot>] [--preset <preset>] [--cpu <cpu>] [--memory <memory>] [--label key=value]... [--env KEY=VALUE]... [--port <port>]... [--auto-suspend <seconds>] [--vmm-type <type>] [--wait]
aca sandbox list --group <group>
aca sandbox get --group <group> --id <id>
aca sandbox delete --group <group> --id <id> [--yes]
aca sandbox stop --group <group> --id <id>
aca sandbox resume --group <group> --id <id>
aca sandbox exec --group <group> --id <id> -c "<command>"
aca sandbox exec --group <group> --id <id> -- <command...>
aca sandbox shell --group <group> --id <id> [--command /bin/bash] [--no-auto-resume]
aca sandbox commit --group <group> --id <id> [--name <image-name>]
aca sandbox stats --group <group> --id <id>

Auto-resume: exec, shell, commit, and stats automatically resume suspended/stopped/idle sandboxes. Disable with --no-auto-resume (shell) or aca config set --auto-resume false (global).

Ports

aca sandbox port add --group <group> --id <id> --port <port> [--anonymous]
aca sandbox port remove --group <group> --id <id> --port <port>
aca sandbox port list --group <group> --id <id>

Egress Policy

Control outbound network access from sandboxes. Rules are evaluated in order — first match wins.

Simple (host allow/deny)

# Block all, allow specific hosts
aca sandbox egress set --id <id> --default Deny --host-allow "*.github.com" --host-allow "*.npmjs.org"

# Allow all (no restrictions)
aca sandbox egress set --id <id> --default Allow

Advanced (file-based: Transform + Rewrite)

For zero-trust patterns (API key injection, URL rewriting), use a policy file:

# Generate a starter template
aca sandbox egress init > policy.yaml

# Edit to add transform/rewrite rules, then apply
aca sandbox egress apply --id <id> --file policy.yaml

# View current policy
aca sandbox egress show --id <id>

# Export as YAML (for version control)
aca sandbox egress export --id <id> > current-policy.yaml

# Get JSON Schema (for editor autocomplete)
aca sandbox egress schema > egress-policy.schema.json

Example policy.yaml — zero-trust API key injection:

defaultAction: Deny

hostRules:
  - pattern: "*.github.com"
    action: Allow

rules:
  # Inject API key — sandbox never sees the secret
  - name: inject-openai-key
    match:
      host: "api.openai.com"
      path: "/v1/*"
      methods: [POST]
    action:
      type: Transform
      headers:
        - operation: Set
          name: Authorization
          value: "Bearer sk-your-api-key"

  # Redirect internal hostname to real endpoint
  - name: rewrite-internal
    match:
      host: "my-api.internal"
    action:
      type: Rewrite
      host: "real-api.azure.com"
      scheme: https

Rule types:

• Allow/Deny — permit or block matching requests
• Transform — modify headers on matching requests (inject auth, remove sensitive headers)
• Rewrite — redirect to a different host/path/scheme

aca sandbox egress set --id <id> --default <Allow|Deny> [--host-allow <pattern>]...
aca sandbox egress apply --id <id> --file <policy.yaml>
aca sandbox egress show --id <id>
aca sandbox egress export --id <id>
aca sandbox egress decisions --id <id>
aca sandbox egress schema
aca sandbox egress init

Lifecycle

aca sandbox lifecycle set --group <group> --id <id> --auto-suspend <seconds> [--mode Memory|Disk]

Disk Images

aca sandbox disk create --group <group> --image <base> [--name <name>] [--entrypoint <cmd>]
aca sandbox disk list --group <group>
aca sandbox disk list-public
aca sandbox disk get --group <group> --id <id>
aca sandbox disk delete --group <group> --id <id>

Snapshots

aca sandbox snapshot create --group <group> --sandbox-id <id> [--name <name>]
aca sandbox snapshot list --group <group>
aca sandbox snapshot get --group <group> --id <id>
aca sandbox snapshot delete --group <group> --id <id>

Volumes

aca sandbox volume create --group <group> --name <name> [--type <type>] [--size <size>]
aca sandbox volume list --group <group>
aca sandbox volume get --group <group> --name <name>
aca sandbox volume delete --group <group> --name <name>
aca sandbox volume-mount --group <group> --id <id> --volume <name> --path <mount-path> [--readonly]

Filesystem

aca sandbox fs ls --group <group> --id <id> [--path /]
aca sandbox fs cat --group <group> --id <id> --path <path>
aca sandbox fs write --group <group> --id <id> --path <path> --file <local-file>
aca sandbox fs rm --group <group> --id <id> --path <path> [--recursive]
aca sandbox fs mkdir --group <group> --id <id> --path <path>
aca sandbox fs stat --group <group> --id <id> --path <path>

Secrets and Content

aca sandbox secret upsert --id <secret-id> --values key1=val1,key2=val2
aca sandbox secret list
aca sandbox secret delete --id <secret-id>
aca sandbox content list

System

aca version
aca doctor

Output

Default output is a simple table. Use -o json for JSON.

Exit Codes

• 0 success
• 1 general error
• 2 auth error
• 3 resource not found
• 4 validation error