acpctl is the command-line interface for the Ambient Code Platform. You can use it to create and manage sessions, switch between projects, and automate workflows from your terminal.

Download the latest binary from your organization’s ACP deployment or build it from source:

cd components/ambient-cli
go build -o acpctl ./cmd/acpctl

Move the binary to a directory in your PATH:

sudo mv acpctl /usr/local/bin/

Verify the installation:

Authenticate with the ACP API server by providing an access token. The token is saved to your local configuration file.

acpctl login --token <your-token>

You can also specify the API server URL and a default project in the same command:

acpctl login --token <your-token> --url https://acp.example.com --project my-project

If the server uses a self-signed certificate, add the --insecure-skip-tls-verify flag:

acpctl login --token <your-token> --url https://acp.example.com --insecure-skip-tls-verify

You can pass the server URL as a positional argument instead of using --url:

acpctl login https://acp.example.com --token <your-token>

Remove saved credentials from the configuration file:

Display the current user, token expiration, API URL, and active project:

Example output for a JWT token:

User:       jane.doe
Email:      jane@example.com
Expires:    2026-04-01T12:00:00Z
API URL:    https://acp.example.com
Project:    my-project

acpctl stores configuration in a JSON file. The default location depends on your operating system: ~/.config/ambient/config.json on Linux, ~/Library/Application Support/ambient/config.json on macOS. Override the location with the AMBIENT_CONFIG environment variable.

Valid keys: api_url, project, pager, access_token (redacted in output).

acpctl config get api_url
# https://acp.example.com

acpctl config set <key> <value>

Valid keys: api_url, project, pager.

acpctl config set api_url https://acp.example.com
acpctl config set project my-project

Most commands operate within a project context. Set the active project before creating or managing sessions.

acpctl project set my-project

Or use the shorthand:

acpctl project my-project

The CLI validates that the project exists on the server before saving it to your configuration.

Or use the shorthand (no arguments):

acpctl create project --name my-project

Optionally set a display name and description:

acpctl create project --name my-project --display-name "My Project" --description "Team workspace"

Get a specific project:

acpctl get project my-project

acpctl describe project my-project

Output is JSON with the full project resource.

acpctl delete project my-project

Add -y to skip the confirmation prompt:

acpctl delete project my-project -y

A project context must be set before you create a session.

acpctl create session --name fix-login-bug --prompt "Fix the null pointer in the login handler" --repo-url https://github.com/org/repo

Get a specific session:

acpctl get session <session-id>

Output in JSON format:

acpctl get sessions -o json

Use wide output for additional columns:

acpctl get sessions -o wide

Monitor session changes in real time:

The watch uses gRPC streaming when available. If the server does not support streaming, the CLI falls back to polling. Press Ctrl+C to stop watching.

acpctl describe session <session-id>

Output is JSON with the full session resource.

Start a session that is in a stopped or pending state:

acpctl start <session-id>

Stop a running session:

acpctl delete session <session-id>

Add -y to skip the confirmation prompt:

acpctl delete session <session-id> -y

You can also manage project settings and users through the get and describe commands.

acpctl get project-settings
acpctl describe project-settings <id>
acpctl delete project-settings <id>

Resource aliases: projectsettings, ps.

acpctl get users
acpctl describe user <username>

Resource aliases: user, usr.

Environment variables override values in the configuration file.

Generate completion scripts for your shell:

# Bash
acpctl completion bash > /etc/bash_completion.d/acpctl
# Zsh
acpctl completion zsh > "${fpath[1]}/_acpctl"
# Fish
acpctl completion fish > ~/.config/fish/completions/acpctl.fish
# PowerShell
acpctl completion powershell > acpctl.ps1

Restart your shell or source the completion file to enable tab completion.