# CLI reference

> Every command and option of the githome command-line client, generated from its source.

Source: https://git.pkgforge.dev/docs/reference/cli

This page lists every command of the `githome` command-line client (version 0.2.0) with all of its options. It is generated from the CLI's own command definitions, so it always matches `githome <command> --help`.

## Install

```sh
curl -fsSL https://git.pkgforge.dev/install | bash      # Linux and macOS
githome setup                                     # sign in through your browser, set up git and gh
```

On Windows, in PowerShell: `powershell -c "irm https://git.pkgforge.dev/install.ps1 | iex"`. The CLI runs on Node.js 26 or later; the script installs a private copy of the Node.js 26 LTS from nodejs.org when yours is older or missing. `githome upgrade` updates it. See [Install and sign in to the CLI](https://git.pkgforge.dev/docs/accounts/cli-sign-in).

## Configuration

| Setting | Where | Notes |
| --- | --- | --- |
| Server URL | `GITHOME_URL`, else `url` in the config file, else `https://git.pkgforge.dev` | Set this to use another Githome server. |
| Token | `GITHOME_TOKEN`, else `token` in the config file | `githome login` signs in through the browser and stores the CLI's token in the config file. |
| Config file | `~/.config/githome/config.json` (`$XDG_CONFIG_HOME/githome/config.json` when set) | Written by `githome login`. |

Commands that work on a repository take `-R OWNER/NAME`. Without it, the CLI uses the `origin` remote of the git repository you are in, when that remote points at the configured server.

Most read commands take `--json` to print the raw API response, for scripts and agents.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | The command failed (an API error, a failed check, a failed run when waiting). |
| `2` | Usage error: unknown command, bad option or missing argument. Help is printed to stderr. |

## Commands

| Command | Summary |
| --- | --- |
| [`agent`](#githome-agent) | Manage agent accounts |
| [`api`](#githome-api) | Make an authenticated API request and print the response |
| [`auth`](#githome-auth) | Git and GitHub CLI integration |
| [`invite`](#githome-invite) | Invite someone by email to an organization |
| [`issue`](#githome-issue) | Work with issues |
| [`login`](#githome-login) | Sign in through your browser (or with a token) |
| [`logout`](#githome-logout) | Sign out: forget the saved token, and revoke it if a browser sign-in created it |
| [`mcp-config`](#githome-mcp-config) | Print an MCP server config snippet for Claude Code and other MCP clients |
| [`migrate`](#githome-migrate) | Import repositories from other forges |
| [`pr`](#githome-pr) | Work with pull requests |
| [`repo`](#githome-repo) | Create, list, view and clone repositories |
| [`run`](#githome-run) | Inspect and control workflow runs |
| [`runner`](#githome-runner) | Run self-hosted workflow jobs on this machine |
| [`secret`](#githome-secret) | Manage Actions secrets |
| [`setup`](#githome-setup) | Set up this computer in one go: sign in, then git and gh |
| [`token`](#githome-token) | Manage personal access tokens |
| [`upgrade`](#githome-upgrade) | Update the CLI to the server's latest build |
| [`variable`](#githome-variable) | Manage Actions variables |
| [`whoami`](#githome-whoami) | Show the account the current token acts as |
| [`workflow`](#githome-workflow) | Run and validate workflows |

### githome agent

Manage agent accounts.

#### githome agent create

Create an agent account and print its token once.

```text
githome agent create <login> [options]
```

Creating an agent mints its first token, which tokens can't do: on git.pkgforge.dev create agents in the web UI (Settings → Agents); the command works against a local development server.

| Option | Description |
| --- | --- |
| `-o, --org ORG` | Owned by this organization instead of you |
| `-n, --name NAME` | Display name |
| `-s, --scope SCOPE` | Token scope: read, write (default) or admin Repeatable. |
| `-e, --expires-days DAYS` | Token lifetime in days (default 90) |
| `--json` | Print raw JSON |

#### githome agent disable

Disable an agent (its tokens stop working).

```text
githome agent disable <login>
```

#### githome agent list

List agents you or your organizations own.

```text
githome agent list [options]
```

| Option | Description |
| --- | --- |
| `--json` | Print raw JSON |

### githome auth

Git and GitHub CLI integration.

#### githome auth git-credential

Git credential helper (used by 'auth setup-git').

```text
githome auth git-credential <get|store|erase>
```

#### githome auth setup-gh

Sign the GitHub CLI (gh) in to Githome with your token.

```text
githome auth setup-gh
```

Runs: gh auth login --hostname <host> --with-token --git-protocol https, with the token
from the config file or GITHOME_TOKEN on its standard input. gh then treats the Githome host
like GitHub Enterprise Server: gh pr create, view, checks, status, merge and the rest work in
clones of Githome repositories, and so does the pull request badge of Claude Code, which
asks gh for its token.

#### githome auth setup-git

Make git use your Githome token for HTTPS remotes.

```text
githome auth setup-git
```

Runs: git config --global credential.<url>.helper "!githome auth git-credential"
(after resetting other helpers for that URL), so clone/fetch/push to the Githome host
authenticate with the token from the config file or GITHOME_TOKEN.

### githome issue

Work with issues.

#### githome issue close

Close an issue.

```text
githome issue close <number> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-r, --reason REASON` | completed (default) or not_planned |
| `-c, --comment TEXT` | Leave a comment too |
| `--json` | Print raw JSON |

#### githome issue comment

Comment on an issue.

```text
githome issue comment <number> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `--json` | Print raw JSON |

#### githome issue create

Open an issue.

```text
githome issue create [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-t, --title TEXT` | Title (required) |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `-l, --label NAME` | Add a label Repeatable. |
| `-a, --assignee LOGIN` | Assign a login Repeatable. |
| `--json` | Print raw JSON |

#### githome issue list

List issues.

```text
githome issue list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-s, --state STATE` | open, closed or all (default: open) |
| `-l, --label NAME` | Only issues with this label |
| `-A, --author LOGIN` | Only issues opened by this login |
| `-S, --search QUERY` | Search text |
| `-L, --limit N` | Maximum number to show (default 30) |
| `--json` | Print raw JSON |

#### githome issue reopen

Reopen an issue.

```text
githome issue reopen <number> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-c, --comment TEXT` | Leave a comment too |
| `--json` | Print raw JSON |

#### githome issue view

Show an issue and its comments.

```text
githome issue view <number> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

### githome migrate

Import repositories from other forges.

#### githome migrate github

Import a GitHub repository (git data, issues, pull requests, releases and more).

```text
githome migrate github <GH-OWNER/GH-REPO> [options]
```

Runs a full server-side import: git data (keeping issue and pull-request numbers), labels,
milestones, issues and pull requests with comments and reviews, branch protection, Actions
variables, release assets and deployment environments. The command follows progress until the
import finishes. Secret values are never read from GitHub; their names are listed to set by hand.

With --local, runs the old client-side import instead (mirror push plus a best-effort recreation
of issues and open pull requests); --issues then also copies labels, issues and comments.

GitHub access uses GH_TOKEN or GITHUB_TOKEN (needed for private repositories; GITHUB_API_URL
selects a GitHub Enterprise API).

| Option | Description |
| --- | --- |
| `-t, --to OWNER/NAME` | Githome repository to create (default: <you>/<gh-repo>) |
| `-p, --private` | Create the repository as private regardless of GitHub's visibility |
| `-l, --local` | Use the old client-side import (no server importer) |
| `-i, --issues` | With --local: also import labels, issues, comments and open pull requests |
| `--json` | Print raw JSON |

#### githome migrate github-org

Import many repositories from a GitHub organization or user.

```text
githome migrate github-org <GH-ORG-OR-USER> [options]
```

Starts a server-side bulk import of every repository in a GitHub organization or user account
(or just the ones named with --repos), into a Githome organization or user. Each repository is
imported in full, the same as "migrate github". The command follows progress until every
repository has finished.

GitHub access uses GH_TOKEN or GITHUB_TOKEN; GITHUB_API_URL selects a GitHub Enterprise API.

| Option | Description |
| --- | --- |
| `-t, --to OWNER` | Githome owner to import into (default: you) |
| `--repos A,B,C` | Comma-separated repository names to import (default: all) |
| `-p, --private` | Create every repository as private |
| `--exclude-forks` | Skip forks |
| `--exclude-archived` | Skip archived repositories |
| `-c, --concurrency N` | Repositories to import at once, 1–8 (default 3) |
| `--json` | Print raw JSON |

### githome pr

Work with pull requests.

#### githome pr checks

Show check status for a pull request.

```text
githome pr checks [<number>] [options]
```

Without a number, shows the open pull request for the current branch. With --watch, polls until no check is pending (waiting up to 2 minutes for the first check to appear, as right after a push), printing the checks whenever they change (on a terminal; otherwise once at the end).

Exit status: 0 when all checks passed, 1 when any failed, 8 when some are still pending (never with --watch).

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--watch` | Wait until no check is pending |
| `-i, --interval SECONDS` | Seconds between polls with --watch (default 10) |
| `--json` | Print raw JSON |

#### githome pr comment

Comment on a pull request.

```text
githome pr comment [<number>] [options]
```

Without a number, comments on the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `--json` | Print raw JSON |

#### githome pr create

Open a pull request.

```text
githome pr create [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-t, --title TEXT` | Title (required) |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `-H, --head BRANCH` | Branch with your changes (default: current branch) |
| `-B, --base BRANCH` | Branch to merge into (default: the repository's default branch) |
| `-d, --draft` | Open as a draft |
| `--intent TEXT` | What this change is for, for reviewers (agents should always set it) |
| `-r, --reviewer LOGIN` | Request a review from this login Repeatable. |
| `--auto` | Turn on auto-merge as it opens: it merges once the base branch's required checks pass and every rule is met |
| `--no-auto` | Keep auto-merge off, even if your setting turns it on for pull requests you open |
| `--json` | Print raw JSON |

#### githome pr diff

Show a pull request's changes as a unified diff.

```text
githome pr diff [<number>] [options]
```

Without a number, shows the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--name-only` | Only list changed file names |

#### githome pr list

List pull requests.

```text
githome pr list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-s, --state STATE` | open, closed, merged or all (default: open) |
| `-L, --limit N` | Maximum number to show (default 30) |
| `-A, --author LOGIN` | Only pull requests opened by this login |
| `-H, --head BRANCH` | Only pull requests from this branch |
| `--json` | Print raw JSON |

#### githome pr merge

Merge a pull request.

```text
githome pr merge [<number>] [options]
```

Without a number, merges the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-m, --merge` | Create a merge commit (default) |
| `-s, --squash` | Squash into one commit |
| `-r, --rebase` | Rebase the commits onto the base branch |
| `-d, --delete-branch` | Delete the head branch after merging |
| `-t, --subject TEXT` | Commit title |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `--match-head-commit SHA` | Only merge if the head is still at this SHA |
| `--admin` | Merge now, bypassing unmet branch rules and any merge queue (repository admins; audited) |
| `--auto` | Turn on auto-merge: merge (or join the merge queue) once every requirement is met |
| `--disable-auto` | Turn off auto-merge (and take the pull request out of the merge queue if it is in it) |
| `--json` | Print raw JSON |

#### githome pr ready

Mark a draft pull request ready for review.

```text
githome pr ready [<number>] [options]
```

Without a number, uses the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--undo` | Convert the pull request back to a draft |
| `--json` | Print raw JSON |

#### githome pr review

Approve, request changes or comment on a pull request.

```text
githome pr review [<number>] [options]
```

Without a number, reviews the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-a, --approve` | Approve |
| `-r, --request-changes` | Request changes |
| `-c, --comment` | Comment without approving |
| `-b, --body TEXT` | Body text (Markdown) |
| `--body-file FILE` | Read the body from a file ('-' for stdin) |
| `--json` | Print raw JSON |

#### githome pr view

Show a pull request.

```text
githome pr view [<number>] [options]
```

Without a number, shows the open pull request for the current branch.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-c, --comments` | Include the conversation |
| `--json` | Print raw JSON |

### githome repo

Create, list, view and clone repositories.

#### githome repo clone

Clone a repository.

```text
githome repo clone <OWNER/NAME> [directory]
```

The token is passed to this one git command as an HTTP header and is never written to .git/config.
Run 'githome auth setup-git' so later fetches and pushes authenticate too.

#### githome repo create

Create a repository.

```text
githome repo create <name> [options]
```

| Option | Description |
| --- | --- |
| `--org ORG` | Create it in this organization |
| `--private` | Only collaborators can see it (default) |
| `--public` | Anyone can see it |
| `-d, --description TEXT` | Description |
| `--default-branch BRANCH` | Default branch name |
| `--json` | Print raw JSON |

#### githome repo list

List repositories you can see.

```text
githome repo list [options]
```

| Option | Description |
| --- | --- |
| `--owner OWNER` | Only repositories owned by this user or organization |
| `--json` | Print raw JSON |

#### githome repo view

Show a repository.

```text
githome repo view [OWNER/NAME] [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

### githome run

Inspect and control workflow runs.

#### githome run cancel

Cancel a queued or running run.

```text
githome run cancel <run-id> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |

#### githome run list

List workflow runs.

```text
githome run list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-b, --branch BRANCH` | Only runs for this branch |
| `-w, --workflow FILE` | Only runs of this workflow (file name or path) |
| `-s, --status STATUS` | Only runs with this status (queued, in_progress, completed, ...) |
| `-e, --event EVENT` | Only runs triggered by this event |
| `-c, --commit SHA` | Only runs for this commit SHA |
| `-L, --limit N` | Maximum number to show (default 20) |
| `--json` | Print raw JSON |

#### githome run logs

Print a job's log.

```text
githome run logs <job-id> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

#### githome run rerun

Re-run a workflow run.

```text
githome run rerun [run-id] [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--failed` | Only re-run the failed jobs and the jobs that depend on them |
| `-j, --job JOB-ID` | Re-run this job and the jobs that depend on it (no run id needed) |
| `--json` | Print raw JSON |

#### githome run view

Show a run and its jobs.

```text
githome run view <run-id> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

#### githome run watch

Follow a run until it completes.

```text
githome run watch <run-id> [options]
```

Polls every 3 seconds and prints job status changes. Exits non-zero unless the run succeeds.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-i, --interval SECONDS` | Seconds between polls (default 3) |

### githome secret

Manage Actions secrets.

#### githome secret delete

Delete an Actions secret.

```text
githome secret delete <NAME> [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-o, --org ORG` | Delete an organization secret instead |

#### githome secret list

List Actions secret names.

```text
githome secret list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-o, --org ORG` | List organization secrets instead |
| `--json` | Print raw JSON |

#### githome secret set

Create or update an Actions secret.

```text
githome secret set <NAME> [options]
```

The value comes from --body, from stdin when piped, or a hidden prompt.
Repository level by default; --org sets an organization secret. An organization secret
reaches every repository unless --visibility (or --repos, which implies selected) says otherwise.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-b, --body VALUE` | Secret value |
| `-o, --org ORG` | Set an organization secret instead |
| `--visibility all|private|selected` | Organization secrets: which repositories get it (all, private or selected) |
| `--repos a,b` | Organization secrets: the repositories that get it, comma separated |

### githome token

Manage personal access tokens.

#### githome token create

Create a personal access token (printed once).

```text
githome token create [options]
```

Tokens can't create tokens, so on git.pkgforge.dev this needs the web UI (Settings → Access tokens); the command works against a local development server.

| Option | Description |
| --- | --- |
| `-n, --name NAME` | Token name (required) |
| `-s, --scope SCOPE` | read, write (default) or admin Repeatable. |
| `-e, --expires-days DAYS` | Days until it expires (1-366, default 90) |
| `-R, --repo OWNER/NAME` | Restrict the token to this repository Repeatable. |
| `--json` | Print raw JSON |

#### githome token list

List your tokens.

```text
githome token list [options]
```

| Option | Description |
| --- | --- |
| `--json` | Print raw JSON |

#### githome token revoke

Revoke a token.

```text
githome token revoke <id>
```

### githome variable

Manage Actions variables.

#### githome variable list

List Actions variables.

```text
githome variable list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

#### githome variable set

Create or update an Actions variable.

```text
githome variable set <NAME> [options]
```

The value comes from --body, or from stdin when piped.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-b, --body VALUE` | Variable value |

### githome workflow

Run and validate workflows.

#### githome workflow list

List the repository's workflows.

```text
githome workflow list [options]
```

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `--json` | Print raw JSON |

#### githome workflow run

Start a workflow_dispatch run.

```text
githome workflow run <workflow-file> [options]
```

The workflow is matched by path (.github/workflows/deploy.yml) or file name (deploy.yml).

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository (default: inferred from the git origin remote) |
| `-r, --ref REF` | Branch or tag to run on (default: the default branch) |
| `-f, --field KEY=VALUE` | Input value Repeatable. |
| `--json` | Print raw JSON |

#### githome workflow validate

Check workflow files for errors.

```text
githome workflow validate [files or directories...] [options]
```

Default: every .yml/.yaml file in .githome/workflows of the current repository, or
in .github/workflows when .githome/workflows is absent. Uses the same parser as the server.
Exits 1 when any file has errors.

| Option | Description |
| --- | --- |
| `--json` | Print raw JSON |

### githome api

Make an authenticated API request and print the response.

```text
githome api <METHOD> <PATH> [options]
```

PATH is relative to /api/v3 (e.g. /user, /repos/OWNER/NAME/pulls) unless it starts with /api/.
--input sends a JSON body from a file, or from stdin with '-'.

| Option | Description |
| --- | --- |
| `-i, --input FILE` | Request body file, or '-' for stdin |
| `-f, --field KEY=VALUE` | Add a string field to the JSON body (or query for GET) Repeatable. |

### githome invite

Invite someone by email to an organization.

```text
githome invite <email> [options]
```

| Option | Description |
| --- | --- |
| `-o, --org ORG` | Organization to join (a site invite is in the dash, and the core answers 403 without it) |
| `-r, --role ROLE` | member (default), admin or owner |
| `--json` | Print raw JSON |

### githome login

Sign in through your browser (or with a token).

```text
githome login [options]
```

Opens your browser on the server's authorize page; approve the sign-in there and the CLI
gets its own token, valid for 90 days and listed under Settings → Access tokens.

On a machine without a browser (over SSH, in a container), --device prints a short code to
enter at <server>/login/device from any browser; the CLI picks this by itself when it sees no
display. For scripts and CI, pass a token with --token, or pipe one in with --with-token
(piping into a plain `githome login` still works). The config file is written with mode 0600.

| Option | Description |
| --- | --- |
| `--url URL` | Server URL (default: GITHOME_URL, the saved URL, or https://git.pkgforge.dev) |
| `--scope SCOPE` | Access to ask for: read, write (default) or admin. You can change it on the authorize page |
| `--web` | Sign in through the browser on this computer (the default in a terminal) |
| `--device` | Sign in with a code you enter in a browser on any device |
| `--token TOKEN` | Use this token (ghome_...) instead of signing in through the browser |
| `--with-token` | Read a token from stdin |

### githome logout

Sign out: forget the saved token, and revoke it if a browser sign-in created it.

```text
githome logout
```

### githome mcp-config

Print an MCP server config snippet for Claude Code and other MCP clients.

```text
githome mcp-config [options]
```

By default the token is written as ${GITHOME_TOKEN} (expanded by clients such as
Claude Code from the environment). Pass --show-token to embed the saved token instead.

| Option | Description |
| --- | --- |
| `--show-token` | Embed the actual token in the snippet |

### githome runner

Run self-hosted workflow jobs on this machine.

```text
githome runner [options]
```

Polls the given repositories for jobs with 'runs-on: [self-hosted, ...]' whose labels this
runner offers, and runs each with the Githome runner agent. Jobs run directly on this machine
with your user's permissions.

The runner registers with each repository and claims jobs with its own token, which can't do
anything else. Register it with a registration token from a repository admin
(POST /repos/OWNER/NAME/actions/runners/registration-token, valid for an hour):

  githome runner -R OWNER/NAME --registration-token ghomerg_... --labels linux

so the machine never holds a personal token, which the jobs it runs could read. The runner's
credentials are saved under ~/.config/githome/runners and used on the next start. Signed in
as a repository admin instead, the runner registers itself with your token.

--ephemeral registers a runner for one job: its token stops working once it takes the job, and
the runner exits when the job finishes.

The runner needs the Githome runner agent (a single Node.js file). Build it from the
Githome repository with:

  pnpm --filter @githome/runner build      # produces containers/runner/dist/agent.mjs

then pass --agent /path/to/agent.mjs or set GITHOME_RUNNER_AGENT.

| Option | Description |
| --- | --- |
| `-R, --repo OWNER/NAME` | Repository to take jobs from (default: the git origin) Repeatable. |
| `-l, --labels a,b` | Extra labels this runner offers, comma separated ('self-hosted' is implied) |
| `-n, --name NAME` | Runner name (default: host name) |
| `--once` | Run at most one job, then exit with its exit code |
| `-a, --agent PATH` | Path to the runner agent (agent.mjs); default GITHOME_RUNNER_AGENT |
| `-w, --work-dir DIR` | Working directory for jobs (default ~/.cache/githome/runner/<name>) |
| `--interval SECONDS` | Seconds between polls when idle (default 5) |
| `-q, --quiet` | Do not echo step output locally (logs still go to the server) |
| `--registration-token TOKEN` | Register this runner with a repository admin's registration token (one repository) |
| `--ephemeral` | Register for a single job, then exit when it finishes |

### githome setup

Set up this computer in one go: sign in, then git and gh.

```text
githome setup [options]
```

Signs in through your browser (or with a code, on a machine without one) unless the CLI is
signed in already, then runs `githome auth setup-git` so git clone, fetch and push use the
sign-in, and `githome auth setup-gh` when the GitHub CLI (gh) is installed. Where Claude Code is
installed, it also adds Claude Code's Githome plugins (githome and githome-ci): they're saved in
~/.claude/githome-plugins and named in ~/.claude/settings.json, so every new Claude Code session loads
them, with their Githome URL setting pointed at this server. Skip that with --no-claude-plugins (or
GITHOME_NO_CLAUDE_PLUGINS=1). For a server other than git.pkgforge.dev (--url, a self-hosted Githome), it
also points Codex's githome MCP server there when Codex is installed (codex mcp add; skip with
GITHOME_NO_CODEX=1). Last, on a terminal, it asks
whether to turn on auto-merge for the pull requests you open (--auto-merge says yes without asking,
--no-auto-merge skips the question). Safe to run again; it brings the plugins up to date.

With --repo OWNER/NAME it sets up an agent environment instead (a Claude Code cloud environment,
Codex, a CI runner), with no browser and no prompt: git and gh use the token in GITHOME_TOKEN
(and GH_ENTERPRISE_TOKEN with GH_HOST for gh) straight from the environment, so no token is written
to disk; the repository is cloned unless it's there already; then a self-test prints one line per
check, saying what to change when one fails, and reports the result to the repository's Agent setup
page. Exits 1 when a check fails. This is what <server>/OWNER/NAME/agent-setup.sh runs.

| Option | Description |
| --- | --- |
| `--url URL` | Server URL (default: GITHOME_URL, the saved URL, or https://git.pkgforge.dev) |
| `--scope SCOPE` | Access to ask for: read, write (default) or admin. You can change it on the authorize page |
| `--web` | Sign in through the browser on this computer (the default in a terminal) |
| `--device` | Sign in with a code you enter in a browser on any device |
| `--repo OWNER/NAME` | Set up an agent environment for this repository instead, with the token in GITHOME_TOKEN (what <server>/OWNER/NAME/agent-setup.sh runs) |
| `--no-clone` | With --repo: don't clone the repository (also GITHOME_NO_CLONE=1) |
| `--clone-dir DIR` | With --repo: where the clone goes (default: GITHOME_CLONE_DIR, /home/user in a Claude Code cloud environment, else the current directory) |
| `--no-report` | With --repo: don't report the result to the repository's Agent setup page |
| `--no-claude-plugins` | Don't add Claude Code's Githome plugins (also GITHOME_NO_CLAUDE_PLUGINS=1) |
| `--auto-merge` | Turn on auto-merge for pull requests you open, without asking (it still waits for each branch's required checks and approvals) |
| `--no-auto-merge` | Don't ask about auto-merge |

### githome upgrade

Update the CLI to the server's latest build.

```text
githome upgrade
```

Downloads <server>/-/cli/githome.mjs and replaces the file this CLI runs from, when it changed.
The install script (curl -fsSL https://git.pkgforge.dev/install | bash) does the same and sets up PATH.

### githome whoami

Show the account the current token acts as.

```text
githome whoami [options]
```

| Option | Description |
| --- | --- |
| `--json` | Print raw JSON |