> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.agenttrunk.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agenttrunk.ai/_mcp/server.

# Connect your first agent

> Authenticate, publish a prompt to staging, and verify an immutable read.

Goal: authenticate and find the workspace your agent should use. No production changes are needed.

## 1. Install the CLI

Use Node.js 22 or newer. The source installation below does not depend on an npm registry release.

```sh
git clone https://github.com/aadi-labs/agenttrunk-plugins.git
cd agenttrunk-plugins
npm ci
npm run build
npm install -g .
agenttrunk --help
```

Review the source before installing it. To avoid a global install, use `node dist/cli/index.js` in place of `agenttrunk` from this checkout.

## 2. Reuse authorization or request approval

If your runtime already supplies `AGENTTRUNK_ACCESS_TOKEN`, do not print it or start another registration. Continue to step 3.

Otherwise:

```sh
agenttrunk auth discover
agenttrunk auth start --email HUMAN_EMAIL
```

Replace `HUMAN_EMAIL` with the authorizing person's email. Give that person the returned verification link. They sign in and approve access. Then run:

```sh
agenttrunk auth complete
```

Enter the approval code through the prompt, not a command argument. Do not obtain it by reading the person's inbox or browser session. A new human must first [create an account and organization](https://www.agenttrunk.ai/signup).

See [authentication](https://docs.agenttrunk.ai/authentication) for credential storage and cloud runtimes.

## 3. Select the workspace

```sh
agenttrunk workspaces
agenttrunk scopes --workspace WORKSPACE_ID
agenttrunk discover --workspace WORKSPACE_ID --channel production
```

Use IDs from the responses and choose the workspace intended for this task. Never select the first workspace implicitly. Follow `nextCursor` where returned, even after an empty page.

An empty successful response is different from an access error. If you are authorized to create a workspace and one is needed:

```sh
agenttrunk workspace-create --name "Customer support"
```

Use its returned ID, then list scopes to find General. Do not create a new organization to work around denied access.

## 4. Upload a prompt to staging

Create a local file named `welcome.md` containing:

```markdown
# Welcome assistant

Greet the user, ask what they want to accomplish, and do not invent account details.
```

Choose a new context key so this exercise does not replace an existing package:

```sh
agenttrunk upload --workspace WORKSPACE_ID --scope SCOPE_ID \
  --key welcome-assistant --title "Welcome assistant" --kind prompt \
  --file ./welcome.md --path prompts/welcome.md
```

This writes to **staging**, not production. Save the returned `revision.id`.
If you cannot publish, request access from your administrator; signing in does
not grant every permission.

## 5. Read exactly what you uploaded

```sh
agenttrunk inspect --workspace WORKSPACE_ID --key welcome-assistant --ref REVISION_ID
agenttrunk read --workspace WORKSPACE_ID --key welcome-assistant \
  --ref REVISION_ID --path prompts/welcome.md
```

Replace `REVISION_ID` with the returned 64-character revision ID. The CLI checks
the file against its manifest before returning it. You should see the welcome
instructions you just uploaded.

**You now have a reproducible context read.** Give that revision ID to your
harness and retain it with the run. Production has not changed.

## Next steps

* Existing context: [inspect a revision and read a file](https://docs.agenttrunk.ai/retrieval).
* New context: [upload a prompt or skill to staging](https://docs.agenttrunk.ai/publishing).
* Ready for production: [request a reviewed release](https://docs.agenttrunk.ai/releases).

Installation, human approval, workspace access, and successful reads are separate checks. Report which one succeeded.