Skip to main content

CLI

Reference for Treq's command-line interface.

The treq command lets you create and inspect workspaces from a terminal. Run commands from inside a Git repository so Treq can detect the repository context.

Commands​

treq add​

Create a new workspace.

treq add <branch_name> [-d <description>] [-l <title>] [-s <source_branch>] [-p <sparse_path>]... [-k <symlink_path>]...
  • branch_name: branch name for the workspace.
  • -d, --description: optional workspace description.
  • -l, --title: optional workspace title.
  • -s, --source-branch: branch to stack the new workspace on.
  • -p, --sparse: sparse checkout path prefix; repeatable. Only matching paths are materialized.
  • -k, --symlink: path to symlink from the home repo into the new workspace; repeatable (e.g. node_modules).

Example:

treq add feat/deps -k node_modules -k target

treq set​

Update workspace metadata.

treq set <workspace_name> [-d <description>] [-l <title>] [-t <target_branch>]
  • workspace_name: workspace branch name.
  • -d, --description: set the workspace description.
  • -l, --title: set the workspace title.
  • -t, --target-branch: set the target branch.

treq st​

Show workspace status.

treq st [workspace_name]

Omit workspace_name to list all workspaces. GitHub pull request information will be included if there is a valid GitHub integration.

treq mv​

Move selected changes from one workspace to another.

treq mv <source> <destination> -f <file> [-f <file> ...]
treq mv <source> <destination> -c <commit> [-c <commit> ...]
  • source: source workspace branch name.
  • destination: destination workspace branch name.
  • -f: file path to move.
  • -c: commit ID to move.

treq agent​

Start an agent session in a workspace.

treq agent <branch> <prompt> [-m <edit|plan>]
  • branch: workspace branch name.
  • prompt: prompt to send to the agent.
  • -m, --mode: permission mode. Use edit or plan.

treq commit​

Create a commit from the pending changes in a workspace.

treq commit <workspace_name> -m <message> [--push]
  • workspace_name: workspace branch name.
  • -m, --message: commit message (required).
  • --push: push the workspace to the remote after a successful commit.

This records working-copy changes in that workspace. It does not merge the workspace into its target. See Commit Management.

treq resolve​

Finish inplace conflict resolution for a conflicted commit that already has a resolve directory under .treq/resolve/<workspace-slug>/.

treq resolve <commit_id> [sides...]
echo '{"path/to/file": "replacement\n"}' | treq resolve <commit_id>
  • commit_id: change id or commit id of the conflicted revision.
  • sides: optional conflict sides to take. Use 1, 2, base, or both.
  • Non-TTY stdin: JSON object of path to full file content replacements.

When the change is clean, Treq rewrites that commit in place and deletes its resolve directory. See Resolve commit conflicts inplace.

treq send​

Send a file or stdin content to the open Treq window for preview. Images show as square thumbnails in the terminal that ran the command; click a thumbnail to open a modal. Text opens a read-only, selectable preview.

treq send <path>
treq send -
echo "notes" | treq send
  • path: existing file on disk. Omit or use - to read stdin.
  • Image types: png, jpg, jpeg, gif, webp, bmp, svg.
  • Everything else is treated as text.
  • Piped stdin is staged under .treq/send/ in the repo (already gitignored).
  • When run inside a Treq terminal, previews attach to that pane via TREQ_PTY_SESSION_ID.

Treq must already have this repository open.