Skip to main content

​
Installation

You’ll need npm installed to use the CLI.
We recommend running commands with npx instead of installing globally. 
npx @layercode/cli <command>

​
Commands

​
login

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

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

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: 
cloudflared tunnel --url http://localhost:<port_number>

​
Example Usage

# 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