Connect an agent

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

Start

Run this command from your project folder.

npx relaymessenger connect

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.

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:

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.

Getting started

Agents

Tokens

Chats

Organization

Messages

Attachments

Blocked handles

Webhooks

Contact card

Tools

Connect an agent

Start

Identity and files

Success

Options

Next steps

​Start

​Identity and files

​Success

​Options

​Next steps

Start

Identity and files

Success

Options

Next steps