CLI Commands
Complete reference for all barrel CLI commands and options.
Launching
barrel
Launch a workspace from the current directory. barrel walks up the directory tree looking for a barrel.yaml file and launches the configured session.
Usage
$ barrel [SHELL]Options
-m, --manifest-path <PATH>Path to barrel.yaml (default: ./barrel.yaml)-p, --profile <PROFILE>Terminal profile to use (default: "default")-w, --worktree <BRANCH>Create/use git worktree for branchExamples
Launch full workspace from current directory
$ barrelLaunch a specific shell from the manifest
$ barrel claudeLaunch with a specific profile
$ barrel -p focusLaunch in a git worktree
$ barrel -w feat/new-featureLaunch from a custom manifest
$ barrel -m ./configs/dev.yamlbarrel -k, --kill <workspace>
Kill a running workspace session. Terminates all panes, closes the tmux session, and cleans up any agent symlinks that were created.
Usage
$ barrel -k <workspace>Options
--keep-agentsKeep agent symlinks instead of cleaning them up--pruneAlso remove the git worktree (use with -w)Examples
Kill a running workspace
$ barrel -k my-projectKill but keep agent files
$ barrel -k my-project --keep-agentsKill workspace and remove worktree
$ barrel -w feat/auth -k my-project-feat-auth --pruneGit Worktrees
Launch workspaces in isolated git worktrees for parallel branch development. Worktrees let you work on multiple branches simultaneously without stashing or switching.
barrel -w, --worktree <branch>
Create or use a git worktree for the specified branch and launch the workspace from there. If the branch doesn't exist, it will be created from the default branch (main/master). The worktree is created as a sibling directory to your repository.
Usage
$ barrel -w <branch>Options
-w, --worktree <BRANCH>Branch name to create/use worktree forExamples
Create worktree and launch workspace
$ barrel -w feat/authLaunch specific shell in worktree
$ barrel -w feat/auth claudeUse existing worktree
$ barrel -w feat/authHow It Works
When you run barrel -w feat/auth:
- If the branch exists locally or on remote, a worktree is created for it
- If the branch doesn't exist, it's created from your default branch
- Your
barrel.yamlis symlinked to the worktree - The workspace launches from the worktree directory
Setup
barrel init
Initialize a barrel workspace in the current directory. Creates a barrel.yaml file with a basic configuration.
Usage
$ barrel initExamples
Initialize a new workspace
$ barrel initbarrel bootstrap
[Experimental] Scan your machine for existing agents and consolidate them using AI. We recommend using barrel agent import for more control.
Usage
$ barrel bootstrapExamples
Auto-discover agents
$ barrel bootstrapSession Commands
Manage running barrel tmux sessions. List active workspaces, create new ones, or kill existing sessions.
barrel session list
List all running barrel sessions. Shows session name, working directory, window count, and attachment status.
Usage
$ barrel session listOptions
-a, --allShow all tmux sessions, not just barrel sessionsExamples
List barrel sessions
$ barrel session listList all tmux sessions
$ barrel session ls --allbarrel session new
Create a new workspace session. Equivalent to running `barrel` or `barrel <shell>`. Launches a workspace from the barrel.yaml manifest in the current directory.
Usage
$ barrel session new [SHELL]Examples
Create new workspace
$ barrel session newCreate with specific shell
$ barrel session new claudebarrel session join <name>
Attach to an existing barrel or tmux session. If already inside tmux, switches to the target session.
Usage
$ barrel session join <name>Examples
Join a session
$ barrel session join my-projectbarrel session kill
Kill a running workspace session. Equivalent to `barrel -k <name>`. Terminates all panes, closes the tmux session, and cleans up agent symlinks.
Usage
$ barrel session kill [NAME]Options
--keep-agentsKeep agent symlinks instead of cleaning them upExamples
Kill current session
$ barrel session killKill named session
$ barrel session kill my-projectKill but keep agents
$ barrel session kill my-project --keep-agentsAgent Commands
Manage your portable agent files. See the Agents documentation for more details.
barrel agent list
List all available agents, both local (in current workspace) and global (in ~/.config/barrel/agents).
Usage
$ barrel agent listExamples
List all agents
$ barrel agent listUsing the alias
$ barrel agents lsbarrel agent import <path>
Import an agent file or directory to the global agents directory. This makes the agent available across all your workspaces.
Usage
$ barrel agent import <path>Examples
Import a single agent file
$ barrel agent import ./.claude/agents/web-developer.mdImport all agents from a directory
$ barrel agent import ./agents/barrel agent new [name]
Create a new agent file. If no name is provided, you will be prompted.
Usage
$ barrel agent new [name]Examples
Create a new agent with name
$ barrel agent new code-reviewerCreate interactively
$ barrel agent newbarrel agent fork <name>
Copy a global agent to the current workspace's local agents directory. This creates a local copy you can customize.
Usage
$ barrel agent fork <name>Examples
Fork a global agent locally
$ barrel agent fork web-developerbarrel agent link <name>
Create a symlink from the current workspace to a global agent. Changes to the global agent will be reflected locally.
Usage
$ barrel agent link <name>Examples
Link a global agent
$ barrel agent link code-reviewerbarrel agent rm <name>
Remove an agent file.
Usage
$ barrel agent rm <name>Examples
Remove an agent
$ barrel agent rm old-agentOther
barrel --version
Display the current version of barrel.
Usage
$ barrel --versionExamples
Check version
$ barrel --versionbarrel --help
Display help information and a list of all available commands.
Usage
$ barrel --helpExamples
Show help
$ barrel --help