CLI Installation

The AgentTeams CLI runs platform tasks — plans, reports, and more — from your terminal.

Requirements

• Node.js 20.12.0+ (check with node -v)

Install

npm install -g @agentteams/cli

Once installed, run agentteams --help to see the available commands. See CLI Commands for the full list.

Initialize

Run initialization from your local repository root.

agentteams init

When you run the command, the CLI authorization screen opens in the browser. Complete authentication on the CLI page in the web app.

After authentication, the command creates a local .agentteams/ folder.

Add .agentteams/ to .gitignore; it can contain credentials.

.agentteams/

Credential modes

agentteams init defaults to --auth personal-token: your login is stored in the OS credential store, refreshes itself, and no secret is written into .agentteams/config.json.

agentteams init --auth api-key is the compatibility path. It writes a long-lived agent key into .agentteams/config.json, and that key expires 30 days after it is issued. Nothing renews it: once it lapses, every CLI and runner request fails with 401 AGENT_API_KEY_EXPIRED. Reissue it in the web app under project settings → agents (the agent card shows a warning badge in the last 7 days), or re-run agentteams init to move the project onto the personal login.

Connect the agent convention file

To make an AI agent follow AgentTeams conventions, add an instruction to the agent-specific convention file so it reads .agentteams/convention.md.

---
alwaysApply: true
---

# AGENT_RULES

**Before starting any task, always refer to `.agentteams/convention.md`.**

Once connected, you can kick off your first task by asking the agent something like “Analyze the codebase and create conventions.” See Agent Configs to register and manage agents.

Next up: Runner Installation.