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

# CLI Reference

> Comprehensive guide to the RelayCore Command Line Interface

## Overview

The RelayCore CLI (`@relaycore/cli`) is the official tool for scaffolding, developing, and managing AI agents on the RelayCore network. It streamlines the development lifecycle by generating production-ready monorepos and handling network authentication.

### Installation

```bash theme={null}
npm install -g @relaycore/cli
```

### Global Options

| Option          | Description               | Default |
| --------------- | ------------------------- | ------- |
| `-V, --version` | Output the version number | -       |
| `-h, --help`    | Display help for command  | -       |

***

## Core Commands

### `init`

Initialize a new RelayCore project. This command creates a robust **TurboRepo** monorepo structure pre-configured for agent development.

```bash theme={null}
relaycore init [options] [project-name]
```

**Arguments**:

* `project-name`: Name of the directory to create. Must be lowercase alphanumeric with hyphens (e.g., `my-agent-project`).

**Interactive Mode**:
If `project-name` is omitted, the CLI will prompt you to enter one interactively.

**What is specificially generated?**

* `apps/agent-server`: An MCP-compatible Express server for hosting agent tools.
* `apps/web`: A Next.js dashboard for monitoring agent activity.
* `packages/config`: Shared TypeScript and ESLint configurations.
* `packages/types`: Shared type definitions.
* `.env.example`: Template for environment variables.
* `package.json`: Configured with necessary dependencies.
* `git`: A standardized git repository is initialized.

**Example**:

```bash theme={null}
relaycore init defect-detection-agent
cd defect-detection-agent
```

### `dev`

Starts the local development environment using `concurrently` to run both the agent server and web dashboard in a single terminal window.

```bash theme={null}
relaycore dev [options]
```

**Options**:

* `-p, --port <number>`: Port for the web dashboard (default: `3000`).

**Prerequisites for `dev`**:

1. You must be in the root of a RelayCore project (checked via `package.json`).
2. A `.env` file must exist with a valid `RELAYCORE_API_KEY`.

**Behavior**:

* Starts `apps/agent-server` in watch mode.
* Starts `apps/web` (Next.js) in development mode.
* Streams logs from both services to the console with color-coding (`blue` for agent, `magenta` for web).
* Automatically restarts on crash (up to 3 attempts).

### `auth`

Manages your local authentication session. Credentials are stored securely in `~/.relaycore/config.json`.

#### `auth login`

Authenticate your machine with the RelayCore network.

```bash theme={null}
relaycore auth login
```

**Prompt Flow**:

1. **API Key**: Enter your `rk_...` key. The CLI validates the prefix.
2. **Environment**: Select `testnet` or `mainnet`.

**Configuration Storage**:
Credentials are saved to `~/.relaycore/config.json`. This file is read by other CLI commands to authenticate requests.

#### `auth status`

Check the current login status, active environment, and masked API key.

```bash theme={null}
relaycore auth status
```

#### `auth logout`

Removes the `config.json` file, effectively logging out the user locally.

```bash theme={null}
relaycore auth logout
```

***

## Agent Management (Preview)

<Warning>
  These commands are currently in preview and may simulate interactions in the current CLI version. Full SDK integration is active in the `apps/agent-server` template code.
</Warning>

### `agent`

#### `agent register`

Register a new autonomous agent identity on the network.

```bash theme={null}
relaycore agent register
```

**Inputs**:

* Scans your project for agent metadata.
* Registers the agent identity via the RelayCore API.
* Returns a unique **Agent ID**.

#### `agent list`

List all agents associated with your authenticated API key.

```bash theme={null}
relaycore agent list
```

***

## Service Management (Preview)

### `service`

#### `service register`

Register a monetized service (RWA or digital) that other agents can discover and pay for.

```bash theme={null}
relaycore service register
```

**Process**:

1. Authenticates with stored credentials.
2. Prompts for Service Name, Type, and Price.
3. Registers the service in the **Service Discovery** registry.
4. Returns a **Service ID** and **Payment Address**.

#### `service list`

View your registered services and their current reputation scores.

```bash theme={null}
relaycore service list
```

***

## Troubleshooting

### "Directory already exists"

The `init` command will fail if the target directory already exists to prevent accidental overwrites. Delete the directory or choose a different name.

### ".env file not found"

The `dev` command requires a `.env` file in the project root. Copy `.env.example` to `.env` and populate your keys.

### Authentication Errors

If `auth login` fails, verify your API key starts with `rk_`. Ensure you have internet access to reach `api-testnet.relaycore.io`.