# 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 links the repository's
Markdown overview and the supported source, history, issue and pull-request
documents. You can also select Markdown from a browser URL by preserving its
query and adding `format=markdown`, for example:

```text
https://git.cafe/<owner>/<repo>?format=markdown
https://git.cafe/<owner>/<repo>/tree/main/src?format=markdown
https://git.cafe/<owner>/<repo>/blob/main/README.md?format=markdown
https://git.cafe/<owner>/<repo>/commits/main?format=markdown
https://git.cafe/<owner>/<repo>/issues/123?format=markdown
https://git.cafe/<owner>/<repo>/pull/123.md
https://git.cafe/<owner>/<repo>/pull/123/diffs.md
```

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](https://git.cafe/docs/index.md#follow-repository-urls) and the
[pull-request Markdown limits](https://git.cafe/docs/collaboration/pull-request.md#read-commits-and-diffs-as-markdown)
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.

## Authenticate deliberately

Install the Cafe CLI and keep the selected API host explicit:

```sh
bun install -g @gitcafe/cli
export CAFE_HOST="https://git.cafe/api"
cafe auth login
cafe auth status
```

`CAFE_HOST` must remain set for later commands (or supply `--host` each time).
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](https://git.cafe/docs/account/device-authorization.md)
and use least privilege. For longer-lived automation, review [personal access
tokens](https://git.cafe/docs/account/personal-access-tokens.md); do not issue a broad token by default.
An injected `CAFE_TOKEN` overrides stored credentials until it is unset.

## Inspect and collaborate

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

```sh
cafe issue list --repo owner/repo
cafe pr diff 123 --repo owner/repo --patch
```

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:

```sh
cafe issue create --repo owner/repo --title "Describe the problem" --body-file issue.md
```

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:

```sh
cafe stack list --repo owner/repo
cafe stack submit --name my-change --base main --dry-run
```

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](https://git.cafe/docs/collaboration/stacks.md)
before removing `--dry-run`.

## Integrations and API

Generic Git mirrors are maintainer-managed repository settings for synchronizing
configured branch history. They do not have a documented Cafe CLI workflow and do
not transfer issues, pull requests, reviews, tags or LFS objects. The
[generic mirror guide](https://git.cafe/docs/integrations/git-mirrors.md) explains limits and uncertain
outcomes. [GitHub integration](https://git.cafe/docs/integrations/github-sync.md) is separate and can
synchronize additional GitHub metadata when installed and authorized.

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

```sh
cafe ci list --repo owner/repo
```

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](https://git.cafe/docs/integrations/buildkite-ui.md) before relying on those results.

For capabilities without a typed command, consult the host's generated
[OpenAPI reference](https://git.cafe/api/openapi.md). 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.