What can I do with GitCafe?#

Use GitCafe's public Markdown documents for anonymous research, then use the Cafe CLI or API for work that needs an identity. This guide is a capability map, not a replacement for each workflow's permissions, limits and recovery instructions. Replace https://git.cafe with your instance's origin, and example owners, repositories, branches, paths and numbers with values from that instance.

Read public repositories without signing in#

Start at https://git.cafe/<owner>/<repo>/llms.txt. It gives a bounded overview of the repository: description, topics, default branch, the root tree, the README's opening, links to the source, history, issue and pull-request documents, and how to continue through MCP, the REST API or git clone. You can also select Markdown from a browser URL by preserving its query and adding format=markdown, for example:

The pull diff document includes bounded text patches where available. Follow its continuation links unchanged: they preserve the pull revision being read. Source tree and history documents similarly provide snapshot links when available. See the documentation index URL grammar and the pull-request Markdown limits instead of guessing .md, .patch or /files routes.

Documents are bounded views, not repository exports. A public resource can move or disappear, and an oversized, binary or budget-limited result says what was omitted. Private resources require authentication and may return 404 rather than confirming that they exist.

Choose how to authenticate#

GitCafe has five ways to authenticate. Each grants a credential that works only on its own path. An MCP token is not accepted by the REST API, an API or auth.md token cannot be used with MCP or Git, and a personal access token cannot replace an MCP connection.

auth.md is intended for one short session. For access that continues past an hour, use API OAuth, MCP or the CLI instead of registering again repeatedly. MCP, API OAuth and auth.md only cover repositories selected at approval; reconnect to add one.

Sign in with the CLI#

The Cafe CLI needs Bun 1.2 or newer; it does not run under Node.js.

cafe auth http setup configures Git to use your login for HTTPS remotes.

The CLI targets https://git.cafe/api by default. For another instance, set CAFE_HOST to its API URL, such as https://gitcafe.example/api, or pass --host with every command. Logins are stored per host, so a command without the host setting uses git.cafe, not the instance you signed in to. Login is a device flow requiring a human to review and approve the requested permissions. Optional profile or credential-management consent is off by default; approve it only when the intended task needs it. Read device authorization and use least privilege. For longer-lived automation, review personal access tokens; do not issue a broad token by default. An injected CAFE_TOKEN overrides stored credentials until it is unset.

Connect an MCP client#

The MCP server is at https://git.cafe/mcp and uses stateless Streamable HTTP, not WebSocket. Read tools work on public repositories without signing in. A write tool or get_me returns HTTP 401 with a WWW-Authenticate challenge naming /.well-known/oauth-protected-resource/mcp, which lists the authorization server and scopes; an invalid or expired token also returns 401. Follow the MCP connection guide to approve repositories.

Clients that discover servers before connecting can read the same server identity from /server.json (MCP Registry format), /mcp/server-card (also at /.well-known/mcp, /.well-known/mcp.json and /.well-known/mcp/server-card.json) or /.well-known/ai-catalog.json. /.well-known/api-catalog lists the REST API and the MCP server. These formats are still drafts; the MCP protocol itself is authoritative for available tools.

Inspect and collaborate#

These read commands work outside a checkout when the repository is explicit:

Mutations need the corresponding repository role and token scope. This command creates an issue, so run it only after the user has approved that effect:

Commands report typed permission and conflict failures. Multi-step operations can partially complete; read the reported durable result before retrying rather than assuming failure rolled everything back.

For stacks, list server state explicitly, then preview local publication from the target checkout with the actual landing branch:

The preview reads local commits and validates the remote without publishing them. Real submission can leave branches or pull requests behind if a later step fails. Follow the stack permissions, publication and recovery guide before removing --dry-run.

Integrations and API#

To bring issues and pull requests from GitHub, use GitHub integration; it synchronizes GitHub metadata once installed and authorized. Generic Git mirrors copy configured branch history only, without issues, pull requests, reviews, tags or LFS objects, and have no documented Cafe CLI workflow. The generic mirror guide explains limits and uncertain outcomes.

GitCafe observes configured Buildkite builds; it does not execute or schedule CI. After a maintainer connects the integration, inspect observations with:

Jobs and logs require configured Buildkite log access. Log sharing is separately controlled and can expose logs to every repository reader, including anonymous readers of a public repository. Review the Buildkite access and log-sharing guide before relying on those results.

For capabilities without a typed command, consult the host's generated OpenAPI reference. Treat its schemas as host-version-specific, authenticate with the same least-privilege rules, and do not infer an operation from a similarly named browser URL.