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

# CLI Reference

> Layercode CLI command reference and usage guide.

## Installation

You’ll need **npm** installed to use the CLI.\
We recommend running commands with `npx` instead of installing globally.

```bash theme={null}
npx @layercode/cli <command>
```

***

## Commands

### `login`

```bash theme={null}
npx @layercode/cli login
```

Opens a browser window to log in and link your terminal to your Layercode account.

During login you’ll be prompted to choose which organization to act on behalf of. The CLI uses this selection for all follow-on commands, so make sure you pick the org that owns the agents you intend to work with.

***

### `init`

```bash theme={null}
npx @layercode/cli init [--agent-id <agent_id>]
```

Initializes Layercode locally, creating an example project and linking an agent.

**Flags**

* `--agent-id <agent_id>`: (optional) Link an existing agent.
  If not provided, a new agent will be created.

***

### `tunnel`

```bash theme={null}
npx @layercode/cli tunnel [--agent-id <value>] [--path <value>] [--port <value>] [--tail]
```

Runs local project with cloudflared tunnel and updates your agent’s webhook URL in the Layercode dashboard.

* `--agent-id=<value>`  Specify the unique identifier of the agent. If omitted, the CLI checks the `LAYERCODE_AGENT_ID` environment variable, then any entry ending with `LAYERCODE_AGENT_ID` in your project `.env` file. If nothing is found, the command will fail.
* `--path=<value>`      \[default: /api/agent] Set the API path to append for the agent endpoint.
* `--port=<value>`      \[default: 3000] Port number to run the tunnel on.
* `--tail`              Continuously stream logs, including CLI messages

**Equivalent to:**

```bash theme={null}
cloudflared tunnel --url http://localhost:<port_number>
```

***

## Example Usage

```bash theme={null}
# Log in
npx @layercode/cli login

# Initialize a new local setup
npx @layercode/cli init

# Start a tunnel for agent abc123 on port 5173 with the api found at /api/voice-agent
npx @layercode/cli tunnel --agent-id=dtv3x3d2 --port=5173 --path=/api/voice-agent --tail
```

***

## Troubleshooting

If you encounter issues:

* Ensure **npm** and **Node.js** are installed and up-to-date.
* Try logging out and back in with `npx @layercode/cli login`.
* If you see `Failed to retrieve Agent information` when starting a tunnel, verify you are logged into the organization that owns that agent. Log out, log back in, and select the correct organization when prompted, then re-run the command.
* By default, your tunnel will set your webhook url path as /api/agent. You should update this with the --path flag based on where your webhook endpoint is inside your application e.g. '/api/agent' or at the root '/' or '/voice-agent'. See our guide on [webhooks for more details](/explanations/webhooks)