# komrad forge connect

Connect a forge with a token read from stdin, or as the engine's GitHub App

[komrad forge](https://komrad.dev/latest/cli/forge.md)

```bash
komrad forge connect <host> [flags]
```

With --method token, the default, the token is read from standard input, or from the file --token-file names. It is never taken as an argument, since arguments are visible to every process on the machine. Pipe it in:

```
gh auth token | komrad forge connect github.com
op read op://vault/github/token | komrad forge connect github.com
komrad forge connect gitlab.com --token-file ~/.config/gitlab-token
komrad forge connect gitlab.example.com --kind gitlab --token-file ~/.config/gitlab-token
```

A GitLab token is a personal access token with the api scope. A remote on an SSH host of its own, such as ssh.gitlab.example.com, reaches the connection for its web host once \[git\] ssh\_hosts in the config names the pair.

With --method github-app nothing is read. The server mints a token from the App named under \[github\_app\] in its own config, checks the installation reaches at least one repository, and records the App's own name as the login. That is the engine's path, where nobody is there to paste a token and the App's key is already on the machine: komrad forge connect github.com --method github-app --engine remote.

With --method rotating-token the token is read as for token, and the host has to run GitLab. The token needs the api scope. The server rotates it at once and keeps only the new one, then rotates it again each day before it expires, so the token you pasted stops working as soon as the connection is made.

The server asks the forge who the credential belongs to before storing anything, so a token that is wrong or expired is refused here rather than found out later. That proves the token is real, not that it can read your repositories: a token with no permissions answers the same question, and shows up later as a repository the forge says it cannot find. github.com and gitlab.com say which forge they run; any other host needs --kind, and --api-url when the API is not at https://<host>/api/v3 for GitHub or /api/v4 for GitLab. The address has to be https.

## Flags

| Flag | Type | Description |
| --- | --- | --- |
| [`--api-url`](https://komrad.dev/latest/cli/forge/connect.md#flag-api-url) | string | where the forge answers API calls, for an enterprise host |
| [`--kind`](https://komrad.dev/latest/cli/forge/connect.md#flag-kind) | string | which forge the host runs, github or gitlab, when the host does not say |
| [`--method`](https://komrad.dev/latest/cli/forge/connect.md#flag-method) | string | how the credential comes: token or rotating-token from stdin, or github-app from the App in the server's config default token |
| [`--token-file`](https://komrad.dev/latest/cli/forge/connect.md#flag-token-file) | string | read the token from this file instead of stdin |

## Inherited flags

| Flag | Type | Description |
| --- | --- | --- |
| [`--config`](https://komrad.dev/latest/cli/forge/connect.md#inherited-config) | stringArray | path to a config TOML, repeatable, later files win over earlier ones |
| [`--engine`](https://komrad.dev/latest/cli/forge/connect.md#inherited-engine) | string | engine to reach: local for this machine, or a file in the config's engines directory, layered over the config |
