# Machine and repo setup (https://docs.vitrinka.ai/dev/cli/setup)



## Credentials [#auth]

One credential per deployment, obtained through a browser approval rather than a pasted secret.

```bash
vitrinka auth login
vitrinka auth status    # deployments this machine holds credentials for
vitrinka auth token     # print the stored token, for shell substitution
vitrinka auth logout
```

## Bind the repo [#bind]

Binds this repository to a workspace on a deployment, so commands run from it know where they belong.

```bash
vitrinka config bind acme --project myapp
```

## The operator persona [#operator]

The default write-attribution name for board writes from this machine. Type your name once and every future write is credited.

```bash
vitrinka config operator            # show
vitrinka config operator "Olivia"   # set
```

<Callout type="warn">
  Agent attribution is unaffected — MCP replies stay authored by the agent.
</Callout>

## Repo wiring [#project]

`setup` onboards a repository: it records the checkout in this machine's ledger, stamps the project and origin into the committed `vitrinka.config.json`, proposes the `@` index policy for review, and wires the agent hooks. It also sends the repository's icon — the first of the well-known files at its root (`public/apple-touch-icon.png` … `favicon.ico`, or Expo's `expo.icon`) — as the project's icon; an icon someone chose in vitrinka stays unless `--force-icon`. `project index` refreshes the path autocomplete index later; `project index configure` edits the policy, `project index status` shows it.

```bash
vitrinka setup
vitrinka project index
```

`setup` detects where this repository belongs — the project this machine already filed it under, else the workspace project that declares its origin, else a new project named after the repository — and shows it on the review; `--project` overrides. A project that spans several repositories — an API, an app, an infra repo — is one project with several repositories, never several projects. `link` files a repository under an existing project (without an argument you pick from the workspace's projects on a terminal), `unlink` takes it out again:

```bash
vitrinka project link acme        # append this repo's origin to project acme
vitrinka project link             # pick from the workspace's projects
vitrinka project unlink
```

Every set-up checkout is recorded in this machine's ledger (`~/.config/vitrinka/config.json`). `vitrinka doctor` reads the ledger against the disk and the workspace and names what drifted — a path that is gone, an origin the project does not declare, a stale setup. `vitrinka doctor --fix` prints the whole plan first, applies the machine and server changes after one confirm, and asks per repository how its committed files should land: a worktree branch with a PR (for a protected main), a commit on the current branch, or the files only.

## The repo's files [#files]

A bound repository carries ONE committed file, `vitrinka.config.json` at its root: `project`, `origins` (origin → workspace), `run` (the stacks pairing and the sessions pipeline boot), `runners` (where test runners write results — `vitrinka setup --runners`), `capture` (`hidpi`: web captures at 2×, on unless set — [`vitrinka config hidpi`](/dev/cli/sets#hidpi)) and the `index` policy. Commit it; it holds no secret. Everything machine-local — captures, artifacts, logs, pair and usertest state — lives in `.vitrinka/`, which ignores itself, so never add a vitrinka line to `.gitignore`. An older `.vitrinka/project.json` is folded into the root file by the next write; `vitrinka doctor` names it.

## Hooks and commit trailers [#hooks]

The work is the record, so setup wires the two places it already happens. In the agent harness, the SessionStart, SessionEnd, Stop and PreToolUse hooks bind a session to its task, cue the todos that fired, gate a hand-back and announce a path-conditioned todo when its file is edited — [session hooks](/pm/work-loop#hooks). In git, a per-repository `prepare-commit-msg` hook runs `vitrinka commit-msg`: on a `vt-<id>` branch (or worktree) it appends a `Vitrinka-Task: vt-<id>` trailer, which is how the GitHub App attaches the commit and the pull request to the task. It never touches merge, squash or fixup messages and always exits 0 — a commit never fails because of vitrinka. A foreign shell hook is chained, never replaced; `setup uninstall` strips exactly its own block.

```bash
vitrinka project commits                 # show the convention for this project
vitrinka project commits --subject on    # also prefix subjects with the task id
vitrinka workspace commit-prefix colon   # the prefix style, workspace-wide
```

The trailer is always written. The subject prefix is opt-in per project, in the workspace's style: `bracket` (`[vt-401]`, the default), `bare` (`vt-401`) or `colon` (`vt-401:`); setting the style takes a workspace admin.

## Tidy the repo [#tidy]

`project tidy` plans moves of legacy capture roots and loose screenshot litter into `.vitrinka/`. It only plans until you pass `--yes`.

```bash
vitrinka project tidy          # plan
vitrinka project tidy --yes    # apply
```

| Flag    | What it does                                                          |
| ------- | --------------------------------------------------------------------- |
| `--yes` | Apply the planned moves.                                              |
| `--all` | Also move loose images and audit files, not just `shot-*.png` litter. |

<Callout type="warn">
  Git-tracked paths are never touched.
</Callout>