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

# Connect and test

> Install the CLI, start your named agent, and complete two FaceTime Audio calls.

Use this after [building your agent](/facetime-cli/build-agent), or with an
existing named LiveKit voice agent. You need your organizer's Chert project UUID,
owner/admin access, and an assigned FaceTime line. See [Projects and lines](/facetime-cli/connect).

## 1. Install and sign in once

Use **macOS or Linux**. The CLI supports Node **22.12+ in the 22.x series, or 24.x**;
the JavaScript starter uses **22.23.2 or 24.x**. Native Windows is not supported.
Check `node --version`; if you use nvm, select the same version in both terminals.

```bash theme={null}
npm install -g @trychert/facetime
chert --version
chert login
chert whoami
```

The default npm install currently gives you **0.1.0-beta.3**, including browser
sign-in and automatic LiveKit credential loading. Expect `chert 0.1.0-beta.3`.
Choose browser sign-in, compare the displayed code,
select your assigned Chert project, and approve. In a remote shell,
`chert login --device` prints the address and code. You do not need to copy a
browser session token for normal sign-in.

## 2. Check the connection from your agent folder

From your agent's folder, where you created `.env.local`:

```bash theme={null}
chert doctor
```

No separate setup step is needed in beta.3. The CLI reads `LIVEKIT_URL`,
`LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` from `.env.local` (or `.env`) in
this folder and uses the Chert project you approved at sign-in. It reports
which file it used. Keep these values in the same LiveKit project as your agent.

Existing shell `LIVEKIT_*` values override the file. If you previously ran
`chert setup`, its saved project and file path still take priority. To switch
to folder loading, run `chert setup --clear` after stopping any active connector.
This keeps your sign-in. See [credential loading](/facetime-cli/commands#credential-loading)
for explicit files and optional setup when running from elsewhere.

Plain `doctor` is read-only. Check that login, project, line, online worker and
LiveKit checks pass. The agent check is skipped until you supply `--agent`.
Resolve busy/offline lines with your organizer before continuing.

## 3. Keep two terminals running

### Terminal A: agent

In the agent folder:

```bash theme={null}
npm run check
npm start
```

These are the supplied starter's scripts. Use your own startup command for an
existing agent. Wait for successful registration with LiveKit. Leave this
terminal running; Chert does not start the program for you.

### Terminal B: Chert

Open a second terminal in the same folder, using the same Node version:

```bash theme={null}
chert doctor --agent team-otter-agent
chert dev --agent team-otter-agent
```

Replace `team-otter-agent` with your exact registered dispatch name.
`doctor --agent` runs a real agent job in a temporary room and may incur provider
usage. It checks membership, not a full conversation. Keep this terminal running
too.

Wait for both of these messages before calling:

```text theme={null}
Connected to Chert. Call readiness is reported separately.
"team-otter-agent" joined a waiting room. Media readiness is not verified. (--no-prewarm turns this off.)
```

<Note>
  Generic `chert dev` automatically prepares and refills waiting rooms. Do not add
  `--muse` to the student starter: that flag is for a separately integrated Muse
  agent, with one prepared session per run. It is not a general avatar switch.
</Note>

## 4. Test two real calls

1. Place a **FaceTime Audio** call to the exact address assigned by your organizer.
2. After connection, say hello. The starter waits for the caller to speak first.
3. Ask a question related to your agent's instructions and a follow-up. Confirm
   it responds to your actual words, then try interrupting once.
4. Hang up from the caller's device. Wait for `Call ended: room removed.` in Chert.
5. Wait for a new waiting-room message, then make a second call. Confirm it
   begins a fresh conversation and cleans up again.

“Connected” and a successful doctor check are not substitutes for this test.
This starter is audio-only; it does not provide avatar video. If no reply arrives,
check the agent terminal for model/key/credit errors before trying repeatedly.

## 5. Stop or change your agent

End the call first. Press **Ctrl+C in Terminal B** and wait for:

```text theme={null}
Stopped. The line no longer routes to this agent.
```

Then stop the agent in Terminal A. To edit, change its instructions or tools and
restart both terminals so a previously prepared room does not use old code.
For the next session, start the agent, then run the short command again:

```bash theme={null}
chert dev --agent team-otter-agent
```

If cleanup or release remains pending, preserve `~/.chert` and ask your organizer
for help. Do not delete state to dismiss the error or let another team take over
before resolving it.

## Common problems

| Symptom | Next step |
| - | - |
| `chert: command not found` | Select the Node version used for installation and reinstall the pinned package. |
| Wrong project / `project_not_signed_in` | Approve login for the intended Chert project; clear or update any old saved setup. |
| `project_role_insufficient` | Ask for owner/admin access to the workshop project. |
| No line / multiple lines / routing error | Ask the organizer to provide exactly one eligible line; see [Projects and lines](/facetime-cli/connect). |
| Busy line / offline worker | Wait for your slot or contact the organizer. Do not blindly use `--takeover`. |
| LiveKit keys missing or wrong project | Run from the agent folder; check `.env.local`, shell overrides, and any saved setup. |
| Agent did not join | Keep the agent running; match the dispatch name and LiveKit credentials in both processes. |
| Connected but silent | Say hello after connection, unmute the caller, and check the agent's model credentials/credits and errors. |
| Old or unexpected agent answers | Stop other instances using the same name; restart both terminals after code changes. |
| Call ends immediately | Record the call time and errors from both terminals; ask the organizer to check the call record. |
| Cleanup remains pending | Preserve state and stop testing until the organizer resolves it. |

For help, share Node/CLI versions, agent name, call time, and relevant error lines.
Never share tokens, API keys, `.env.local`, or unsanitized logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.