Borg Live Debug

Borg Live Debug Skill

You have direct access to a running borg-web-ui Docker container. Use this to run real borg/borg2 commands, inspect actual output, and use that ground truth to write code, tests, and fixes.

Container Details

• Container name: borg-web-ui
• Borg 1 binary: borg (e.g. /usr/bin/borg or via PATH)
• Borg 2 binary: borg2 (e.g. /usr/local/bin/borg2)
• Working dir: /app
• Data dir: /data (database, SSH keys, repos)
• Working user for borg ops: borg (use gosu borg or su borg -c)

How to exec into the container

Run commands inside the container using:

docker exec -it borg-web-ui <command>
# or as the borg user:
docker exec -u borg borg-web-ui <command>
# or for multi-step shell sessions:
docker exec borg-web-ui bash -c "<cmd1> && <cmd2>"

Workflow

When the user asks to debug, test, or develop borg functionality:

Step 1 — Verify the container is running

docker ps --filter name=borg-web-ui --format "{{.Names}} {{.Status}}"

If it's not running, tell the user to start it: docker compose up -d

Step 2 — Probe the environment

# Check borg versions available
docker exec borg-web-ui bash -c "borg --version 2>/dev/null; borg2 --version 2>/dev/null"

# Check what repos are configured (from DB or env)
docker exec borg-web-ui bash -c "ls /data/ 2>/dev/null"

Step 3 — Run the borg command and capture output

Run the exact borg command you need to test. Always capture both stdout and stderr:

docker exec -u borg borg-web-ui bash -c "BORG_PASSPHRASE='' borg list /path/to/repo 2>&1"
# For borg2:
docker exec -u borg borg-web-ui bash -c "BORG_PASSPHRASE='' borg2 rinfo /path/to/repo 2>&1"

Key environment variables to set when running borg commands:

• BORG_PASSPHRASE — passphrase (empty string if unencrypted)
• BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes — skip prompts for unencrypted repos
• BORG_RSH — custom SSH command if needed
• BORG_REMOTE_PATH — path to borg on remote (for SSH repos)

Step 4 — Use output to write code

After seeing the real output:

• Parse the exact JSON structure (use borg ... --json wherever possible)
• Match error messages exactly for error handling
• Match field names precisely in Python code
• Write tests using real fixture data from the output

Common borg2 command cheat sheet (key differences from borg1)

Create a temporary test repo inside the container

When you need a throwaway repo to test against:

# Create a temp repo (unencrypted for easy testing)
docker exec -u borg borg-web-ui bash -c "
  BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes \
  borg init --encryption=none /tmp/test-repo-1 2>&1 &&
  echo 'test content' > /tmp/testfile.txt &&
  borg create /tmp/test-repo-1::archive-1 /tmp/testfile.txt 2>&1 &&
  borg list /tmp/test-repo-1 2>&1
"

# Same for borg2
docker exec -u borg borg-web-ui bash -c "
  BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes \
  borg2 rcreate --encryption=none /tmp/test-repo-2 2>&1 &&
  echo 'test content' > /tmp/testfile.txt &&
  borg2 create /tmp/test-repo-2::archive-1 /tmp/testfile.txt 2>&1 &&
  borg2 list /tmp/test-repo-2 2>&1
"

JSON output for parsing

Always prefer --json flag to get structured output you can map directly to Python:

docker exec -u borg borg-web-ui bash -c "borg list --json /tmp/test-repo-1 2>&1"
docker exec -u borg borg-web-ui bash -c "borg info --json /tmp/test-repo-1::archive-1 2>&1"
docker exec -u borg borg-web-ui bash -c "borg2 rinfo --json /tmp/test-repo-2 2>&1"

Inspect the Python app code live

# Check what Python modules are available
docker exec borg-web-ui bash -c "cd /app && python3 -c 'from app.core.borg2 import *; print(\"ok\")'"

# Run a quick Python snippet against the live app
docker exec borg-web-ui bash -c "cd /app && python3 -c \"
import asyncio
from app.core.borg2 import borg2_rinfo
result = asyncio.run(borg2_rinfo('/tmp/test-repo-2'))
print(result)
\""

Cleanup

After debugging, clean up temp repos:

docker exec borg-web-ui bash -c "rm -rf /tmp/test-repo-1 /tmp/test-repo-2 /tmp/testfile.txt"

Rules

1. Always run the command first, then write code — never guess borg output format.
2. Use --json wherever possible — map the exact field names into Python dicts.
3. Capture stderr — borg sends warnings and errors to stderr; use 2>&1.
4. Test both binaries — when working on borg2 features, also verify borg1 is unaffected.
5. Clean up temp repos after debugging sessions.
6. If container is not running, tell the user before attempting anything.