manage-agent

Drive

amctl

to manage agent-manager resources end-to-end. Locks the non-obvious patterns of the CLI into a predictable shape so calls don't silently fail or return half-empty envelopes.

Your approach: Show a short plan before starting. Use ✓ for success, ✗ for failure. When something fails, diagnose the likely cause and propose a fix before trying another approach.

Flag shape is owned by
amctl <verb> --help
, not this skill. Skills can't stay in lockstep with CLI versions;

--help

always reflects the installed binary. This document carries the things

--help

won't tell you: when to call which verb, what its output really means, and where the CLI's surface is misleading.

Reference files

references/troubleshooting.md
— symptom → cause → fix table for non-obvious CLI behavior (empty envelopes, misleading statuses, async deletes, crash-loop signatures, shell traps). Load when an
```
amctl
```
call surprises you.
references/triage.md
— diagnostic flow for "build is Completed but the agent isn't really running" (build → logs → metrics → traces). Load when verifying a fresh deploy or chasing a runtime-only failure.

Install

command -v amctl

returns a path, skip.

Otherwise: ask the user whether they want to install it themselves or have you do it.

"
amctl
isn't installed. Would you like me to install it for you, or would you prefer to do it yourself?"

If they want you to install it: Run the bundled wrapper. It checks idempotency, execs the upstream installer, and prints a one-line status with the PATH outcome.

bash

bash <absolute-path-to-skill>/scripts/install-amctl.sh

After the installer finishes, stop and tell the user: open a new terminal so the updated

PATH

is picked up, then run:

bash

amctl login --url <instance-url>

amctl login

is an interactive browser-redirect flow. Always defer to the user's terminal — never attempt login from this session, even against localhost.

Once the user confirms login, verify with

amctl project list --json

— NOT

amctl context show

context show

only reflects the instance URL and looks identical for an unauthed half-configured context as for a logged-in one. The real auth canary is any project-scoped call: failure surfaces as

error.code: NO_ORG

Iron rules

Always pass
--json
. Errors come back as a structured envelope (
```
error.code
```
,
```
error.message
```
,
```
error.additionalData.details
```
). Success envelopes always carry
```
data
```
plus context (
```
instance
```
,
```
org
```
,
```
project
```
, sometimes
```
environment
```
,
```
agent
```
). Exception:
```
agent build logs
```
is raw text.
Run
amctl <verb> --help
before every call you haven't made this session, and always before
create
/
update
. Flag sets evolve. Never infer flag absence from this doc, prior conversation, or a sibling agent's example.
Always pass
--project <name>
explicitly on project-scoped commands. Be aware
```
amctl context link
```
exists and a user may have linked a directory (check
```
amctl context show
```
), but do not link/unlink yourself — keep every command self-describing.

Runtime commands (
logs
,
metrics
,
traces
,
trace
,
traces export
) require
--env <name>
. Use

--env default

for local dev.

Builds are identified by
buildName
(e.g.
```
hotel-booking-agent-1778760196718
```
), NOT
```
buildId
```
(UUID). Build commands take the agent name as a positional arg, not
```
--agent
```
.
amctl agent get
does not show deployment health. Its
```
status
```
field is usually empty. Verify liveness with
```
agent logs
```
or
```
agent metrics
```
. See
```
references/triage.md
```
.
Validation errors come batched in
```
error.additionalData.details
```
. Read the full list, fix everything, retry — don't fix one at a time.

Verb map

What exists, what it's for, and where

--help

lives. For exact flags on any row, run

amctl <verb> --help

Verb	Use to	Notes
`amctl context show`	Inspect current instance / org / linked project.	Auth-blind: shows URL even when unauthed. Not a login check.
`amctl context link` / `unlink`	Bind a directory to a project / agent.	See iron rule 3.
`amctl project list` / `get`	Discover projects, confirm auth works.	`project list` is the login canary.
`amctl project create` / `delete`	Manage projects.	`delete` needs `-y` .
`amctl agent list` / `get`	Discover agents, read agent config.	`get` does NOT show liveness or deployment env — see iron rule 6.
`amctl agent create`	Create + auto-build + auto-deploy in one call.	Required flags vary by `--subtype` ( `chat-api` / `custom-api` ) and `--build-type` ( `buildpack` / `docker` ) and `--provisioning` (default / `external` ). Always `--help` first.
`amctl agent deploy`	Re-deploy a built image, optionally with new env.	`-y` to accept env-conflict prompt.
`amctl agent delete`	Remove an agent.	Async — `agent list` may still show it for 5–15s after `data.deleted: true` .
`amctl agent build list`	Enumerate builds, newest first.	Entries carry both `buildId` (UUID) and `buildName` . Use `buildName` everywhere downstream.
`amctl agent build get`	Status / percent / step list for one build.	`data.status` ∈ `Pending` / `Running` / `Completed` / `Failed` . Agent name is positional.
`amctl agent build create`	Trigger a fresh build without recreating the agent.	Optional commit pin.
`amctl agent build logs`	Raw text build log (image pull, buildpack, workload CR apply).	NOT JSON. May be empty for 10–30s after a fresh build — retry.
`amctl agent logs`	Runtime pod logs.	Requires `--env` . Filter with `--since` / `--level` / `--grep` / `--sort` — run `--help` for current set.
`amctl agent metrics`	CPU / memory time-series for the running pod.	Requires `--env` . Returns `data.{cpuLimits,cpuUsage,memoryLimits,memoryUsage}` , each an array of `{time, value}` .
`amctl agent traces`	List OTel traces from the agent's spans.	Requires `--env` . `--condition` narrows to built-in heuristics (errors, latency, token usage, tool failures, span count) — run `--help` for the current names and thresholds. Filtered response uses `data.count` ; unfiltered uses `data.totalCount` .
`amctl agent trace`	Span detail for a single `traceId` .	Add `--span <spanId>` for one span's full attrs / events. Note: trace detail uses `durationNs` , trace list uses `durationInNanos` .
`amctl agent traces export`	Bulk dump full span data for every trace in a window.	`--since` is required.

End-to-end recipe

The flow for "create an agent and confirm it's actually serving traffic." For exact flags at each step, run

amctl <verb> --help

against your installed binary.

Example plan to announce before you start:

text

I'll create the agent and confirm it's actually serving traffic.
Here's what I'll do:
✦ Confirm amctl is installed and you're logged in
✦ Run `amctl agent create --help` to lock onto the current flag set
✦ Create the agent (auto-builds + auto-deploys to `default`)
✦ Poll the build until Completed or Failed
✦ Confirm liveness via logs / metrics
✦ Pull a recent trace once there's traffic

Create. Run
```
amctl agent create --help
```
to see the current required flag set for your
```
--subtype
```
/
```
--build-type
```
/
```
--provisioning
```
combination, then call
```
amctl agent create <name> --project <p> ... --json
```
. The create call auto-builds and auto-deploys to the lowest environment (
```
default
```
locally).

Poll the build.

amctl agent build list <agent> --project <p> --json

returns newest-first; pull

data.builds[0].buildName

. Poll

amctl agent build get <agent> <buildName> --project <p> --json

until

data.status

Completed

Failed

. In zsh, name the loop variable anything except

status

— zsh reserves

$status

as a read-only alias for

$?

Confirm liveness.
```
agent get
```
won't tell you. Tail
```
amctl agent logs <agent> --project <p> --env default --since 5m --json
```
and look for app-level output past the otel-tracing init container, or check
```
amctl agent metrics ...
```
for ≥1
```
memoryUsage
```
sample. If you see neither after ~3 min, run the full diagnostic in
```
references/triage.md
```
.
Watch traces once there's traffic.
```
amctl agent traces <agent> --project <p> --env default --since 1h --json
```
. Empty list = agent hasn't run, window too narrow, or auto-instrumentation was disabled at create. Drill into a specific trace with
```
amctl agent trace <agent> <traceId> ...
```
.

When anything in this flow returns a surprising envelope, check

references/troubleshooting.md

before reaching for a workaround.

manage-agent

NPX Install

Tags

SKILL.md Content

manage-agent

Reference files

Install

Iron rules

Verb map

End-to-end recipe