SpecBridge SpecBridge | Docs Guide

This guide walks you through the full SpecBridge workflow — from installing the CLI to viewing specs in the dashboard.

Prerequisites

  • Python 3.11 or later
  • Access to a SpecBridge instance (your admin will provide the URL)
  • A registered user account

1. Install the CLI

uv tool install "https://specbridge.online/downloads/cli/$(curl -sS https://specbridge.online/downloads/cli/latest.txt)"

Verify the installation:

specbridge --version

2. Log In

specbridge login

You will be prompted for your username and password.

3. Create a Tenant

Only administrators can create tenants. Log in to the dashboard as an admin and navigate to the admin panel to create a new tenant with a unique slug (e.g., acme-corp).

4. Create a Space

Spaces are organizational units within a tenant (like JIRA projects). An admin or tenant owner can create a space with:

  • Name — display name
  • Slug — short code (max 6 characters, e.g., CORE)
  • Mode — sprint or backlog

5. Create a Project

Projects are delivery units that can link to Git repositories. Initialize a project from the CLI:

mkdir my-specs && cd my-specs
specbridge init my-project

If the server project does not exist yet, the CLI creates it automatically on first push.

6. Add and Commit Specs

Create spec documents in your working directory, then track them:

specbridge add my-spec.md
specbridge commit -m "Initial draft of my spec"

7. Push to the Server

specbridge push

This uploads your specs to the server so your team can see them. If you belong to zero spaces you will get an error; if you belong to exactly one, it is used automatically; if more than one, you are prompted.

8. View in the Dashboard

Open the dashboard. Your spec appears in the board and list views. Click into a spec to see its detail page with comments, versions, stage plans, and status transitions.

9. Pull Changes

Collaborators can pull the latest spec versions:

specbridge pull

This downloads the latest changes from your teammates.

Next Steps