CLI Installation Issues

"specbridge: command not found"

Ensure uv tool bin directory is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

ImportError or missing dependencies

Make sure you are using Python 3.11 or later:

python --version
uv tool install spec-bridge

uv tool install fails

Ensure uv is installed and up to date.

Authentication Issues

Login fails

• Verify your username and password
• Ensure the server URL is correct
• Check that you have an active account

Token expired

Session tokens refresh automatically. If login still fails, try:

specbridge login

"Not authorized" errors

• Ensure you are logged in (specbridge whoami)
• Verify that you have the required permissions for the action
• Check that your active tenant is correct (specbridge switch tenant <slug>)

Push/Pull Issues

"You are not a member of any space"

Create a space in the dashboard or ask an admin or tenant owner to add you to a space.

"Multiple spaces detected"

You belong to more than one space. The CLI will prompt you to choose one. Alternatively, set your active space:

specbridge switch space <space-slug>

Push fails with "Project not found"

Ensure the project exists on the server. You may need to run specbridge init first.

Merge conflict detected

If two people edited the same spec at the same time, you will see a conflict message. Resolve the conflicting sections in your spec files and try pushing again.

Dashboard Issues

Page shows "403 Forbidden"

You do not have permission to access that page. Contact an admin to adjust your permissions.

Extension draft not appearing in dashboard

• Ensure you are using the same tenant in both the extension and dashboard
• Drafts expire after 6 hours

Notifications not updating

Notifications arrive in real time. If you are not seeing updates, try refreshing the page.

Server Issues

Server not reachable

Contact your administrator to verify the server is running and accessible at the expected URL.