Composal

Documentation

Search Composal documentation

Search public documentation, commands, and release notes.

Browse documentation

Get Started

Quickstart

Install the Composal CLI, sign in, set up coding agents, then clone or import a repository and land your first change.

On this page

1. Install the CLI

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

Terminal
curl -fsSL https://dl.composal.ai/install.sh | sh

The executable is com. The installer also keeps vex as a compatibility alias for existing scripts. If you already have Vex installed, rerun the installer above to add com; your saved sign-in and configuration are kept.

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

Terminal
com --help

No filesystem driver is required for cloning, changes, reviews, or deployment. You can add an optional MacFUSE virtual mount later. On Windows, install Composal inside a WSL Linux distribution.

2. Sign in

com login opens a browser authorization flow and writes the resulting control-plane token to ~/.config/vex/config.toml. com whoami confirms the active identity.

Terminal
com login
com whoami

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

3. Set up your coding agents

com setup detects supported harnesses, shows the plan, and writes only the integrations you confirm. Skills, MCP tools, and Agent Context are independent options:

  • Agent Skills teach an agent how to use Composal safely.
  • MCP tools let an agent take live repository actions.
  • Agent Context is opt-in project hook support that captures and scrubs session context for the exact commit.
Terminal
com setup
# For a repeatable install:
com setup --yes --targets codex,claude-code,cursor --with-mcp

Inspect the target matrix with com setup --list-targets --format json, and check an existing install with com setup doctor.

4. Get your first repository

Every organization has a Home repository at <org>/home. Clone it to begin from the organization-level working copy.

Terminal
com clone <org>/home
cd home

If local FUSE is available, com clone <org>/home --fs virtual creates a daemon-backed virtual working copy. The normal checkout is always a supported path.

The Composal Home repository browse view with trunk selection, clone action, and source tree

5. Import a project

For an existing GitHub repository, use the guided importer. It handles authorization, repository selection, conversion, and durable resume state.

Terminal
com repo import --org <org-slug>

The local-assisted path is usually fastest for large repositories. If the terminal closes or the network drops, resume the printed session:

Terminal
com repo import --resume <session-id>

For non-interactive use, name the source explicitly and confirm it:

Terminal
com repo import --org <org-slug> \
  --github-repository <owner>/<repo> \
  --yes --no-tui

An agent can follow the hosted import prompt. For a direct import into a chosen Home path, use com import github <owner>/<repo> --org <org> --path apps/<slug> --virtual-repo <slug> --yes.

6. Land your first change

Start a change above your trunk, describe it, submit it for review, then request landing. Repeat com new to make dependent changes.

Terminal
com new main
# Edit files.
com describe -m "feat: my first change"
com submit --target main
com land #1

Use your repository’s trunk name in place of main when it differs. com land #N keeps CI, approval, and queue-order gates in place.

The Composal landing queue with authority and queue controls

Next steps

You now have a signed-in CLI, agent integrations, and a repository with a landed change. Continue with source control, the CLI reference, or CLI configuration.