← Back to articles

Getting started with Barge

4 min read

The Barge CLI connects your machine to your dashboard account. Once a session is accepted, the work can queue and run without your laptop. The series index covers the underlying workflow.

What you need

You need an invited Barge account and the barge CLI on PATH. Released binaries do not require Bun. Git and tar are needed to package a local handoff; running the CLI from source also requires Bun.

The installer is in the public distribution repository. Download and inspect install.sh before running it, or select a binary for your platform from its releases. Check command -v barge after installation.

barge setup

Connect the CLI to your account:

barge setup --url https://getbarge.dev

It opens the dashboard in a browser, waits for you to sign in and approve, then writes ~/.config/barge/config with the URL and a freshly minted CLI token. The file is restricted to mode 0600; setup does not print the token. Later commands read this config automatically. Explicit BARGE_URL and BARGE_TOKEN environment values take precedence, so check for stale overrides if the CLI targets the wrong deployment.

Check installation, reachability, and authentication separately:

  • barge is on PATH: command -v barge
  • The control plane is reachable: its /healthz responds
  • The token authenticates: barge list succeeds without a 401

Connect your tools

In first-run setup or Settings, connect your own GitHub identity and a supported AI credential. The repository must be accessible to your account and covered by the Barge GitHub App installation. Configuring the platform’s App credentials is an operator task, not a prerequisite for every hosted user.

Save your API key or connect a supported subscription, then choose the agent and credential type. Barge agents: API keys and subscriptions explains those choices. Personal sessions use your credentials, not the deployment’s shared provider keys.

Three ways to start

From a Linear issue. From the repository root:

barge linear owner/repo main BSH-123 --alive

The control plane folds the issue’s text, comments, attachments, and linked or mentioned issues into the session task, so the worker resolves those references itself. A design source it cannot open stops the session as blocked rather than shipping unverified work.

Cloud start without an issue. Same shape, task text instead of an issue:

barge cloud owner/repo main "add rate limiting to the public API" --alive

Hand off current local work. When the work is already in progress on your machine:

barge create "finish the retry logic on the webhook handler" --brief-file brief.md --alive

The brief is a short Markdown file you or your local agent write first. Include the goal, success criteria, decisions, completed work, relevant files, validation, unresolved issues, and next action. Packaging collects reachable commits, a binary-safe tracked patch, and non-ignored untracked files.

The scanner checks the tracked patch and eligible untracked text up to 1 MiB. It does not scan committed history or comprehensively check binary, oversized, or unreadable files. A finding stops packaging by default and reports kind and location, not the secret value. Remove the secret and retry; do not enable the explicit --allow-secrets override automatically.

These examples use --alive to enable queued follow-ups. Omit it for a one-shot run that does not accept dashboard or CLI messages.

Size the worker

Defaults live in .barge.yml and can be overridden per session:

barge cloud owner/repo main "task" --cpu 4 --memory 8192 --timeout-minutes 180

The minimal config

Create .barge.yml in the repository root. This example is for a Bun project; replace the commands with your repository’s own setup and checks:

version: 1
setupCommand: bun install
testCommand: bun test
validationCommand: bun run check
commandTimeoutSeconds: 600
worker:
  cpu: 2
  memoryMb: 4096
  timeoutMinutes: 120
exclude: []

Unknown fields are rejected on purpose, so a misspelled key fails fast. The legacy .cloud-handoff.yml name still works through a compatibility window that ends 2026-12-31.

Follow and finish

After a successful start returns a session URL, the work has been accepted server-side and the laptop can disconnect. It may still be queued or provisioning, not yet running. barge get <session-id> shows its state, barge wait <session-id> waits for a terminal state, and barge cancel <session-id> requests cancellation.

For a session created with --alive, barge message <session-id> <text> or the dashboard chat queues another instruction. The worker consumes messages after the initial PR and verification using a resumable agent thread, not by interrupting the build. The follow-up window stays within the original runtime budget, which defaults to 120 minutes. --alive does not extend that budget.

Sessions without keep-alive, sessions without a resumable thread after the build, and terminal sessions reject messages. Once the worker is gone, use the separate PR-comment /handoff continuation flow rather than sending another message to the finished session.

The worker opens a draft PR before running its review/fix loop and manual verification. UI work can include browser evidence; API and CLI changes use appropriate non-browser checks. Read the reports for failed, blocked, partial, or skipped work rather than assuming every stage passed.

The merge remains your decision. The final article uses an illustrative day to show how a bounded cloud run fits around other work; follow it at the series index.

Barge is in private beta. Join the waitlist to get an invitation.