bloc

Version: v0.2.0

CLI tool for Forgejo operations. Replaces scattered curl commands across commune agent skills with a unified interface.

Install

uv pip install -e .

Quick start

# Set token directly (testing/CI)
export BLOC_TOKEN=<your-forgejo-token>

# Or inside the sandbox container, FORGEJO_TOKEN is already set as an rbw entry name
# bloc resolves it automatically via: rbw get "$FORGEJO_TOKEN"

# List open PRs (infers repo from git remote)
bloc pr list

# Target a specific repo
bloc pr list --repo commune/skills

# Get PR details with reviews
bloc pr get 42 --repo commune/skills

# Create a PR
bloc pr create feature-branch --title "Add new feature" --repo commune/skills

# Approve a PR
bloc pr review 42 approve "LGTM" --repo commune/skills

# Check merge readiness
bloc pr checks 42 --repo commune/skills

# Merge
bloc pr merge 42 --repo commune/skills

# List open issues
bloc issue list --repo commune/skills

# Create an issue
bloc issue create "Bug report" --body "Details here" --repo commune/skills

# Comment on an issue or PR
bloc comment post 42 "Working on this" --repo commune/skills

# List labels for a repo
bloc label list --repo commune/skills

# Create a label (idempotent — safe to run twice)
bloc label create "status:ready" --color "#0e8a16" --repo commune/skills

# Apply labels to an issue or PR
bloc label apply 10 "status:claimed" --repo commune/skills

# Remove labels
bloc label remove 10 "status:claimed" --repo commune/skills

# Claim an issue (applies status:claimed + self-assigns)
bloc claim 42 --repo commune/skills

# Release a claimed issue
bloc release 42 --repo commune/skills

# View PR diff
bloc pr diff 42 --repo commune/skills

# Check governance requirements (approval thresholds, stale reviews)
bloc governance check-threshold 42 --repo commune/skills

Global flags

These flags work at any position in the command — before or after the subcommand:

bloc --json pr list --repo commune/skills
bloc pr list --repo commune/skills --json

Flag	Short	Description
--repo OWNER/REPO	-r	Target repository (default: infer from git remote)
--json	-j	Output as JSON for scripting
--debug		Show HTTP request/response details
--dry-run		Show what would happen without making changes

Auth chain

Token is resolved in this order:

1. BLOC_TOKEN env var — used directly (for testing/CI)
2. rbw get "$FORGEJO_TOKEN" — if FORGEJO_TOKEN is set, it's treated as an rbw entry name
3. rbw get "Forgejo API Token (agent)" — default fallback
4. Error with diagnostic message

Commands

Pull requests

Command	Description
bloc pr list	List PRs. Use --state closed or --state all to include merged/closed PRs
bloc pr get NUMBER	Show PR details including description, labels, and all reviews
bloc pr create BRANCH	Create a PR from BRANCH into --base (default: main). Set --title and --body
bloc pr review NUMBER ACTION MSG	Submit a review. ACTION: approve, request-changes, comment
bloc pr merge NUMBER	Merge a PR. Use --method (merge/squash/rebase), --no-delete-branch to keep branch
bloc pr diff NUMBER	Show the diff for a PR. Use --stat for summary only
bloc pr checks NUMBER	Show merge readiness: conflicts, approvals, and review states

Issues

Command	Description
bloc issue list	List issues. Use --state closed or --state all to include resolved issues. Filter with --labels
bloc issue get NUMBER	Show issue details including labels and assignees
bloc issue create TITLE	Create an issue. Set --body, --labels (IDs), --assignees (usernames)
bloc issue close NUMBER	Close an issue

Comments

Command	Description
bloc comment list NUMBER	List comments on an issue or PR
bloc comment post NUMBER MESSAGE	Post a comment on an issue or PR

Labels

Command	Description
bloc label list	List labels for a repo. Use --org ORG for org-level labels
bloc label create NAME	Create a repo label. Idempotent — succeeds if it already exists. Set --color, --description
bloc label delete NAME	Delete a repo label by name
bloc label apply NUMBER LABEL...	Add labels to an issue/PR by name (auto-creates missing labels)
bloc label remove NUMBER LABEL...	Remove labels from an issue/PR by name

Claim/Release

Command	Description
bloc claim NUMBER	Claim an issue — applies status:claimed label and self-assigns. Auto-creates the label if missing
bloc release NUMBER	Release a claimed issue — removes label and unassigns
bloc claim --list	List all currently claimed issues

Governance

Command	Description
bloc governance check-threshold NUMBER	Verify PR has minimum approval threshold (2 approvals, or Brad approval during testing)
bloc governance check-stale NUMBER	Check if PR has stale approvals (approvals submitted before the latest commit)
bloc governance can-review NUMBER	Check if caller can review a PR (not author, not already reviewed)

Development

# Run CLI
uv run bloc --help

# Run tests (125 tests, respx-mocked)
uv run --extra dev pytest tests/ -v

# Lint
uv run --extra dev ruff check src/ tests/