Search Composal documentation

Search public documentation, commands, and release notes.

Install the CLI

Install the Composal CLI on macOS, Linux, or Windows with WSL. Sign in, choose your organization, and prepare your first hosted browser verification run.

Contents

1. Install the CLI

Install Composal on macOS or Linux as your normal user. No sudo is needed.

On Windows, run the Linux CLI inside a WSL2 Linux distribution. Open its Linux terminal and run the commands below there. Keep your CLI configuration and project files in the WSL filesystem. Running agent setup inside WSL configures agents in that Linux environment; it does not configure a Windows desktop app.

Bash
curl -fsSL https://dl.composal.com/install.sh | sh

When signed in to Composal, use the install copy button in your organization's command menu or Verify setup to install and sign in together. The command sets that organization as your CLI default and keeps your normal user access. Its login grant lasts 45 minutes and works once. An expired or already-used command still installs the CLI; run com login afterward to connect.

The executable is com. Composal installs into ~/.composal/bin and configures PATH for Bash, Zsh, and Fish automatically. Open a new terminal if prompted, then check the installation:

Bash
com --version
com verify --help

Verify runs browsers remotely; you do not need a local browser installation to launch a hosted run.

2. Sign in

Create a Composal account with Google, GitHub, or your email and password. For email signup, verify your address using the link we send you. Your first sign-in creates a workspace for you and opens its setup. With a company email the workspace is named after the domain (ada@acme-labs.io gets Acme Labs); with a personal email it is named after you. You can rename it in workspace settings. Existing users can sign in directly.

When available, Continue with ChatGPT also creates or signs in to your Composal account. If you already have an account with the same email, sign in using your existing method, then open Settings → Account → Link ChatGPT. Linking keeps your Composal workspaces and their permissions. ChatGPT sign-in provides identity only; connect a model subscription separately from your private agent’s model picker.

com login opens browser authorization and saves your local profile to ~/.config/composal/config.toml. Confirm the active identity:

Bash
com login
com whoami

On a headless machine, use com login --no-browser and complete the printed verification URL elsewhere. To use a personal token, use the prompted com login --token flow so it does not land in shell history.

For Google or GitHub sign-in, choose the provider account linked to your Composal account. New users can create an account with a verified provider email without an invitation. If you were invited to a workspace, use the email address from your invitation to join it.

3. Choose an organization

You need Verify enabled for your organization and administrator access to configure targets or launch runs. Choose a default organization, or pass --org <org> to verifier commands:

Bash
com context switch <org>
com verify environments list --org <org> --json
com verify admin scenarios list --org <org> --project <project> --json

To invite teammates, open Settings → Organizations, choose your organization, then open Team. Owners and admins can manage member roles and send, copy, resend, or revoke invitations on the same page. Admins can switch teammates between Member and Admin; only owners can assign or change the Owner role. Other members can view the member list.

4. Prepare a Verify run

A run needs a ready environment revision and saved project Scenarios. Register an accessible HTTP(S) URL or prepare a managed shadow, define your user journeys and expected outcomes, and store test-account values in your project's Credentials.

Follow Start a run for the dashboard path. The verifier CLI reference walks through registering a URL, importing scenarios, reviewing a plan, and launching browser agents. For a manual run against an existing URL, you do not need to clone or import a repository.

Next steps