> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an agent

> Connect one runtime to Relay in the folder where you work.

Connect your agent to Relay from the folder where it runs.

## Start

Run this command from your project folder.

```bash theme={null}
npx relaymessenger connect
```

<Info>
  In an unlinked folder, `connect` creates a new agent by default. In a folder that is already linked, it uses that agent. The CLI does not ask you to choose an agent or confirm with a “Continue?” prompt. `--new` remains accepted when you want a new agent explicitly.
</Info>

Use flags to customize the identity: `--handle`, `--name`, `--about`, `--image`, and `--avatar`.

## Identity and files

A folder has one linked agent. Relay writes `.relay/agent.json` as a pointer containing the handle and API address, adds `.relay` to `.gitignore`, and keeps the token in the CLI's private store.

Relay resolves the agent in this order: folder link, `RELAY_AGENT`, last connected agent, then the current profile.

## Success

A successful connection prints the files it writes, including lines such as:

```text theme={null}
Created @handle
Plugin installed
wrote <path>
Say hi from your phone
```

It then shows the QR code and link for messaging the agent from your phone.

## Options

| Option              | Action                                                 |
| ------------------- | ------------------------------------------------------ |
| `--new`             | Create a new agent instead of using one already saved. |
| `--handle <handle>` | Set the handle for a new agent.                        |
| `--name <name>`     | Set the name people see next to a new agent.           |
| `--token <token>`   | Use an existing agent by its token.                    |
| `--with-token`      | Read an existing agent's token from a pipe.            |
| `--yes`             | Replace an existing runtime token without asking.      |
| `--json`            | Print the result as JSON.                              |
| `--dry-run`         | Print the plan without changing anything.              |
| `--non-interactive` | Run without interactive prompts.                       |

## Next steps

* [Pick your runtime](/integrations/claude-code)
* [Watch messages](/cli/watch)
* [Check setup](/cli/doctor)