Getting Started

This guide walks you through installing Bithyle, authenticating, and pushing your first repository.

Install

The quickest way to install is with the install script:

curl -fsSL https://bithyle.com/install.sh | sh

This installs three binaries into ~/.local/bin:

  • bithyle -- the CLI client
  • git-remote-bithyle -- git remote helper for bithyle:// URLs
  • bithyle-runner -- CI runner daemon (optional, for self-hosted compute)

Or download a tarball manually from the Downloads page and extract it to a directory in your PATH.

Authenticate

Configure the CLI to talk to your forge:

bithyle auth setup

This prompts for the server URL and your credentials, then writes a config file to ~/.config/bithyle/config.toml. You can manage multiple servers -- each gets a [server.<name>] section.

Verify your setup:

bithyle auth whoami

Create a Repository

Create a repo under your namespace:

bithyle repo create my-project

Push Code

Bithyle uses jj's change model, but you push via standard git. Add the remote to your repo:

git remote add bithyle bithyle://bithyle.com/you/my-project

Then push:

git push bithyle main

Or use bithyle push which handles remote setup automatically:

bithyle push

The push triggers Bithyle's pre-receive hook, which extracts change IDs from commit headers and builds the change graph. You'll see it appear on your repository's Changes tab.

View Changes

List change graphs for a repository:

bithyle changes

View a specific change graph:

bithyle change <graph-id>

View diffs:

bithyle diff <change-id>

Review and Merge

Submit a review on a change:

bithyle review <change-id> --verdict approve

Enqueue a change graph for merging:

bithyle merge enqueue <graph-id>

The merge queue rebases the graph onto trunk, runs CI, and fast-forwards on success. You can check queue status:

bithyle merge status

Set Up CI

Add a .forge/pipeline.toml to your repository root:

[pipeline]
triggers = ["push"]

[[jobs]]
name = "build"
commands = ["make build"]
timeout_seconds = 600

[[jobs]]
name = "test"
depends_on = ["build"]
commands = ["make test"]

See the Pipeline Reference for the full format.

To run CI, you need a runner. See the CI Runner guide for setup.

Next Steps