CLI Reference

The bithyle CLI is the primary tool for interacting with a Bithyle forge from the command line.

Global Options

All commands accept:

• --server <name> -- target a specific server from your config (default: first configured server)
• --help -- show help for any command

Authentication

bithyle auth setup

Interactive setup for forge credentials. Prompts for server URL and login credentials, writes to ~/.config/bithyle/config.toml.

bithyle auth whoami

Display the currently authenticated user.

bithyle auth servers

List all configured servers.

Repositories

bithyle repo list [NAMESPACE]

List repositories in a namespace. If no namespace is given, lists repos in your own namespace.

bithyle repo create NAME

Create a new repository under the current namespace.

Changes

bithyle changes

List change graphs for the current repository (detected from git remote).

bithyle change GRAPH_ID

Show details of a specific change graph, including its changes, review status, and CI status.

bithyle diff CHANGE_ID

Display the diff for a specific change.

bithyle push

Push the current branch to the forge. Automatically sets up the bithyle remote if needed.

bithyle open

Open a draft change graph for review. Marks the graph as ready for review.

Reviews

bithyle review CHANGE_ID

Submit a review on a change.

Options:

• --verdict <approve|request-changes|comment> -- review verdict
• --body <text> -- review comment body

bithyle comment CHANGE_ID

Add a comment to a change (legacy alias for review with comment verdict).

Issues

bithyle issues list

List issues for the current repository.

Options:

• -s, --state <open|closed|all> -- filter by state (default: open)

bithyle issues show ID

Display an issue and its replies.

bithyle issues create BODY

Create a new issue.

bithyle issues close ID

Close an issue.

bithyle issues reopen ID

Reopen a closed issue.

bithyle issues reply ID BODY

Add a reply to an issue.

bithyle issues tag ID TAG

Add a tag to an issue.

bithyle issues untag ID TAG

Remove a tag from an issue.

Merge Queue

bithyle merge enqueue GRAPH_ID

Enqueue a change graph for merging. The merge queue rebases it onto trunk, runs CI, and fast-forwards on success.

bithyle merge dequeue GRAPH_ID

Remove a change graph from the merge queue.

bithyle merge status

Display the current merge queue status.

CI

bithyle ci status

List CI runs for the current repository.

bithyle ci show RUN_ID

Show details of a specific CI run, including job statuses and logs.

Tooling

bithyle describe

Print a human-readable summary of all CLI commands.

Options:

• --json -- output a machine-readable tool manifest (JSON)

Git Remote Helper

The git-remote-bithyle binary is installed alongside the CLI. It enables bithyle:// URLs in git:

git remote add forge bithyle://bithyle.com/namespace/repo
git push forge main
git clone bithyle://bithyle.com/namespace/repo

Authentication uses v4 HMAC signing from your ~/.config/bithyle/config.toml.

Configuration

Config lives at ~/.config/bithyle/config.toml:

[server.bithyle]
url = "https://bithyle.com"
username = "you"
signing_key = "hex-encoded-key"

Multiple servers are supported. Use --server <name> to target a specific one, or the CLI uses the first entry by default.