CLI reference

Use com <command> --help for the full flag list accepted by your installed version. This page keeps the task-level command shapes together; the CLI changelog carries every released version’s notes.

Start here

com login
com whoami
com clone <org>/<repo>
com status

For a newly initialized or cloned Composal repository, use Composal-native commands. com git remains available for deliberate Git interoperability work.

Repositories and changes

# Create and describe work.
com new main
com describe -m "Describe the change"

# Review and land it.
com submit --target main
com change show #42
com land #42

# Bring your graph up to date.
com pull
com sync --target main

Import an existing source when you need it in a Composal Home repository:

com repo import --org <org-slug>
com import git https://git.example.com/team/repo.git \
  --org <org> --path apps/<slug> --virtual-repo <slug> --yes

See source control, remote Git sync, and the Git comparison for the workflow boundaries.

The experimental live-mode guide covers com clone --live, com live snapshot, describe, new, edit, bookmarks, rebase, watcher lifecycle and offline recovery. Live directories use that explicit command surface; the ordinary submit/pull workflow above applies to local checkouts.

Local Change UI

Run com ui in a native checkout to open your current change in the browser. The bundled interface shows the local graph and the same diff viewer used by Composal Change pages. Editor saves and terminal operations update it live. Open View And Attach Transcripts to read saved conversations or attach an eligible local session to the selected commit. Submitted changes include earlier patchsets with their source commit shown; attachment uses Composal's existing privacy checks and cannot be undone.

com ui
com ui --no-open
com ui --port 49170

Edit a message, drag a change onto a new parent, or use Move Or Combine Changes for keyboard-accessible rebase and squash controls. Choose a target and Submit Change to review the preflight and publish the selected commit. Submitted changes use the existing remote Fold Into Parent operation.

The server listens on loopback and stops with Ctrl-C. No Node or Rails runtime is required. Keep its printed launch URL private. Local undo is available only for the last uninterrupted local UI operation; it does not undo publication or Fold. Conflicts are resolved in your editor. Graphs above 200 entries and patches above 8 MiB require the CLI, and Git-only checkouts must be converted first.

Clean up a working copy

A checkout that has been in use for a while accumulates residue: workspaces whose directory you deleted by hand, workspaces whose work has landed and that now hold only an empty commit, and empty undescribed commits from sessions that went nowhere. com prune finds them.

Start by looking. On its own the command reports and changes nothing:

com prune

Each candidate is listed under its category — stale (the working-copy directory is gone), landed (the working copy is empty and sits on trunk), and dangling (an empty, undescribed commit nothing points at) — with the reason it qualifies. A Left alone section lists what was examined and deliberately not offered.

Then remove what you want:

com prune --interactive        # tick items in a picker: space, a for the group, enter
com prune --yes                # take the whole plan
com prune --only stale --yes   # one category at a time

Both paths apply in a single operation, so com undo reverses a whole prune rather than one workspace of it.

For scripts and agents, the plan is machine-readable and the dry run is the default, so an unattended run cannot remove anything by accident:

com prune --format json
com prune --only dangling --older-than 30 --yes

Two boundaries worth knowing:

• Nothing on disk is deleted unless you pass --delete-files, which removes the working-copy directory of a landed workspace. That part is not covered by com undo.
• A commit that cannot be read is never acted on. It is reported with the reason instead, so a repository with a damaged object stays prunable everywhere else.

Workspaces registered before Composal recorded workspace paths cannot be checked against the filesystem. They are reported rather than offered; --include-unlocatable offers them anyway when no directory of that name exists under your workspaces root.

Agents and context

com setup --yes --targets codex,claude-code,cursor --with-mcp
com setup doctor --format json
com agent-checkpoints doctor
com session doctor --remote --format json

Agent Context and MCP are explicit opt-ins. Use agent setup for the capability split and recovery checks.

Hosting and registry

com deploy create --app <app> --service web --env production --watch
com deploy logs --app <app> <allocation-id> --task web
com docker setup
com hub login --registry registry.vex.sc
com hub push <image> --org <org> --repo <item> --tag <tag>

See hosting for the managed runtime workflow and Composal Hub for container images.

Release notes

The CLI version is the version running on your machine:

com --version

Read detailed notes and compatibility-relevant changes in the Composal CLI changelog.