​

Bossa CLI Reference

​

Agent Documentation (bossa init)

bossa init

# Append to project files
bossa init --project --yes

# Append to specific file
bossa init --path ./AGENTS.md --yes

# Update to latest (e.g. after upgrading bossa)
bossa init --path ./AGENTS.md --overwrite --yes

# MCP-only instructions (for Cursor, Claude, LangChain)
bossa init --path ./AGENTS.md --mode mcp --yes

​

Authentication

​

Workspaces

​

Upgrade to Pro

​

Workspace Context (Active Workspace)

​

Usage

​

API Keys

​

Filesystem Commands

​

Agent Mode

• --json or -j — Output JSON for machine parsing
• BOSSA_CLI_JSON=1 — All commands return JSON without passing the flag
• --safe — On read-only commands (ls, read, grep, glob, stat, tree, du), signals auto-approval for agent harnesses that gate tool execution
• Exit codes: 0 success, 1 error (not found, validation), 2 auth failure

​

ls — List directory

bossa files ls [path]

• path (default: /): Directory to list
• Output: One item per line; directories end with /
• JSON (with --json or BOSSA_CLI_JSON=1): {"items": [{"name": "a/", "type": "directory"}, {"name": "b.txt", "type": "file", "size": 1024, "modified": "2026-03-06T10:00:00Z"}]}

​

read — Read file

bossa files read <path>

• path: File path
• Output: Raw content to stdout (for piping)
• JSON: {"path": "...", "content": "..."}

​

write — Write file

bossa files write <path> [--content "..." | stdin]

• path: File path
• —content, -c: Content string (or read from stdin)
• Output: “Wrote /path” or {"path": "...", "wrote": true}

echo "Hello" | bossa files write /hello.txt
bossa files write /note.txt --content "Note content"

​

grep — Search contents

bossa files grep [pattern] [--path /] [--regex] [--case-sensitive] [--output-mode matches|files_with_matches|count]

• pattern: Literal or regex pattern (optional if using —all-of/—any-of/—none-of)
• —path, -p (default: /): Scope to subtree
• —regex: Treat pattern as regex
• —case-sensitive: Case-sensitive match
• —whole-word: Match whole words only
• —output-mode, -o (default: matches): matches | files_with_matches | count
• —max-matches (default: 100): Max results
• —offset: Pagination offset
• —all-of: All terms must match (AND). Repeatable.
• —any-of: At least one term must match (OR). Repeatable.
• —none-of: Exclude lines matching any. Repeatable.
• —context-before: Lines before each match
• —context-after: Lines after each match

​

glob — Find by pattern

bossa files glob <pattern> [--path /]

• pattern: Glob (e.g. *.md, **/*.py)
• —path, -p (default: /): Scope to subtree
• Output: One path per line
• JSON: {"paths": ["/a.md", "/b.md"]}

​

edit — Replace substring

bossa files edit <path> --old <string> --new <string> [--all]

• path: File path
• —old, -o: String to replace
• —new, -n: Replacement string
• —all, -a: Replace all occurrences (default: first only)

​

stat — File metadata

bossa files stat <path>

• path: File path
• Output: size, modified, created
• JSON: {"path": "...", "size": N, "modified": "...", "created": "..."}

​

tree — Directory tree

bossa files tree [path] [--depth N]

• path (default: /): Directory to show
• —depth, -d: Max depth (default: unlimited)

​

du — Disk usage

bossa files du [path]

• path (default: /): Directory to summarize
• Output: Size per directory

​

delete — Delete file

bossa files delete <path>

​

put — Upload single file

bossa files put <local_file> [--target /path]

• local_file: Local file path
• —target, -t: Remote path (default: / + basename)

​

batch — Batch operations

bossa files batch

​

upload — Bulk upload

bossa files upload <local_path> [--target /prefix] [--include-hidden]

• local_path: Directory or file
• —target, -t: Remote path prefix
• —include-hidden: Include hidden files (. prefix)

​

Environment Variables

​

CLI vs MCP