Skip to content
OpenCharly

agentteams-cli

Recipe card from the charly-agentteams plugin (Images — the deployable catalog).

agentteams-cli

Section titled “agentteams-cli”

The compiled-in charly agentteams management CLI for the AgentTeams controller REST API — a command:agentteams plugin. A plain net/http REST client: no upstream agt binary (the upstream AgentTeams CLI), no SDK. Use it to manage a running AgentTeams deployment: create and inspect Workers, apply Teams and Humans, and check controller health. A Human is a real person — a human-in-the-loop participant with an identity and permission tier — who can observe and intervene in the Rooms their permissions allow.

Command tree

Section titled “Command tree”
  • charly agentteams status — controller health + manager/worker/team/human counts.
  • charly agentteams worker list|get|create|update|apply|delete — Worker CR (custom resource) management (apply includes ZIP/package worker import).
  • charly agentteams team apply|list|get|delete — Team management.
  • charly agentteams human apply|list|get|delete — Human management.
  • charly agentteams apply -f <file> — declarative YAML apply (create-or-update per kind).
  • charly agentteams config — the resolved controller endpoint and token source.

Endpoint and token discovery

Section titled “Endpoint and token discovery”
  • Endpoint: AGENTTEAMS_CONTROLLER_URL (default http://127.0.0.1:8090 — the controller’s port 8090 as host-mapped by the box’s default auto-allocation; set it to the actual host-mapped port when it differs).
  • Token: AGENTTEAMS_AUTH_TOKEN env, else AGENTTEAMS_AUTH_TOKEN_FILE file (the upstream runtime contract). The controller mints the admin SA (service account) token to /var/run/agentteams/cli-token — on a pod substrate pull it out with charly cp <deploy> :/var/run/agentteams/cli-token <local>.

The agentteams: check verb

Section titled “The agentteams: check verb”

The plugin ALSO serves the declarative agentteams: check verb — the controller-probe counterpart of the CLI, authored as a check: step in a candy/box plan. It is HOST-BASED (the mcp pattern): the provider resolves the controller’s in-venue :8090 to a host-routable address over the reverse channel (a published port on the pod substrate, a live ssh -L forward on the vm substrate), pulls the admin SA token from the venue, and probes with the SAME REST client the command uses (R3 — one surface covers the CLI and every bed). Methods:

  • agentteams: status — controller health + resource counts.
  • agentteams: manager-running — poll until a manager reaches Running (name: pins a specific manager; default: any).
  • agentteams: worker-running — create the named Worker CR (default bed-worker) and poll until Running WITH its Matrix room provisioned and the room alias resolvable on the homeserver.
  • agentteams: worker-list — list the workers the controller manages.

The verb’s method + method-exclusive modifiers ride the desugared plugin input, validated at runtime against the served #AgentTeamsInput schema. It skips under charly check box (no live controller on a disposable podman run --rm).

Declarative apply

Section titled “Declarative apply”

charly agentteams apply -f <file> walks the YAML docs and applies each kind (create-or-update) through the REST API — mirroring agt apply -f.

Worker create

Section titled “Worker create”
charly agentteams worker create --name my-worker --model gpt-5-mini [--runtime openclaw] [--image <image>] [--skills a,b] [--expose 8080,3000] [--no-wait]

--no-wait returns immediately after the controller accepts the request; by default the CLI polls up to --wait-timeout (default 3m) for the Worker to report Ready. --runtime selects the worker runtime — openclaw (an AI agent gateway runtime) is the default.

Example

Section titled “Example”
export AGENTTEAMS_CONTROLLER_URL=http://127.0.0.1:8090
export AGENTTEAMS_AUTH_TOKEN_FILE=/path/to/cli-token
charly agentteams status
charly agentteams worker list

Cross-References

Section titled “Cross-References”