Utilisation de la CLI

Cette page couvre les mécanismes d'entrée et de sortie de la CLI ant qui s'appliquent à tous les points de terminaison. Pour l'installation et l'authentification, consultez le Démarrage rapide. Pour enchaîner des commandes et gérer les ressources avec un contrôle de version, consultez Scripts et automatisation avec la CLI.

Structure des commandes

Les commandes suivent un modèle ressource action. Les ressources imbriquées utilisent des deux-points :

ant <resource>[:<subresource>] <action> [flags]

Exécutez ant --help pour obtenir la liste complète des ressources, ou ajoutez --help à n'importe quelle sous-commande pour afficher ses options.

Les ressources en version bêta (notamment les agents, sessions, déploiements, environnements et compétences) se trouvent sous le préfixe beta:. Les commandes de cet espace de noms envoient automatiquement l'en-tête anthropic-beta approprié pour cette ressource, vous n'avez donc pas besoin de le passer vous-même. Utilisez --beta <header> uniquement pour remplacer la valeur par défaut (par exemple, pour opter pour une version de schéma différente).

ant models list
ant messages create --model claude-opus-4-8 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

Options globales

Formats de sortie

auto affiche le JSON de manière lisible et constitue la valeur par défaut pour les commandes qui créent ou modifient des ressources. Les commandes de liste et de récupération utilisent par défaut l'explorateur interactif lors de l'écriture vers un terminal, et le JSON formaté lorsqu'elles sont redirigées via un pipe. Remplacez l'une ou l'autre valeur par défaut avec --format :

ant models retrieve --model-id claude-opus-4-8 --format yaml

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00:00:00Z"
...

Les points de terminaison de liste paginent automatiquement. Dans les formats par défaut, chaque élément est écrit séparément (un objet JSON compact par ligne en mode jsonl, un flux de documents YAML en mode yaml), ce qui s'intègre proprement dans head, grep et les filtres --transform.

Explorateur interactif

L'explorateur est une interface textuelle (TUI) de type plier-et-rechercher pour parcourir les réponses volumineuses. Les touches fléchées développent et réduisent les nœuds, / lance une recherche, q quitte. Les commandes de liste et de récupération l'ouvrent par défaut lorsqu'elles sont connectées à un terminal. Passez --format explore pour l'ouvrir explicitement :

ant models list --format explore

Transformer la sortie avec GJSON

Utilisez --transform pour restructurer les réponses avant l'affichage. L'expression est un chemin GJSON. Pour les points de terminaison de liste, la transformation s'exécute sur chaque élément individuellement, et non sur l'enveloppe :

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-5"}

Extraire une valeur scalaire

Pour capturer un champ unique sous forme de chaîne sans guillemets (par exemple, l'ID d'une ressource nouvellement créée), associez --transform à --raw-output. Le résultat s'affiche sans guillemets JSON et est prêt à être assigné à une variable shell :

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-sonnet-4-6}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

Passer des corps de requête

Le mécanisme d'entrée approprié dépend de la forme des données : utilisez des options pour les champs scalaires et les valeurs structurées courtes, redirigez un document via stdin pour les corps imbriqués ou multilignes, et utilisez des références @file pour insérer le contenu de fichiers dans n'importe quel champ de type chaîne ou binaire.

Options

Les champs scalaires correspondent directement à des options. Les champs structurés acceptent une syntaxe souple de type YAML (clés sans guillemets, guillemets optionnels autour des chaînes) ou du JSON strict :

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

Les options répétables construisent des tableaux. Chaque --tool ou --event ajoute un élément :

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-4-8}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Redirigez un document JSON ou YAML vers stdin pour fournir le corps complet de la requête. Les champs provenant de stdin sont fusionnés avec les options, les options ayant la priorité. Ici, version est le jeton de verrouillage optimiste renvoyé par un retrieve antérieur, et $AGENT_ID a été capturé comme dans Extraire une valeur scalaire :

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Les heredocs fonctionnent de la même manière et sont pratiques pour le YAML multiligne. Mettez le délimiteur entre guillemets (comme dans <<'YAML') pour désactiver l'expansion des variables à l'intérieur du corps.

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-4-8
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

Références de fichiers

Les options qui prennent un chemin de fichier, comme --file sur la commande d'upload, acceptent un chemin simple :

ant beta:files upload --file ./report.pdf

Pour insérer le contenu d'un fichier dans un champ de type chaîne, préfixez le chemin avec @ :

ant beta:agents create \
  --name "Researcher" --model '{id: claude-sonnet-4-6}' \
  --system @./prompts/researcher.txt

À l'intérieur des valeurs d'options structurées, entourez le chemin de guillemets. Pour envoyer un PDF à l'API Messages :

ant messages create \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}' \
  --transform 'content.0.text' --raw-output

La CLI détecte le type de fichier et encode automatiquement les fichiers binaires en base64. Pour forcer un encodage spécifique, utilisez @file:// pour du texte brut ou @data:// pour du base64. Échappez un @ littéral en début de chaîne avec une barre oblique inverse (\@username).

Débogage

Ajoutez --debug à n'importe quelle commande pour afficher la requête et la réponse HTTP exactes (en-têtes et corps) sur stderr. Les clés API sont masquées.

ant --debug beta:agents list

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2023-06-01
X-Api-Key: <REDACTED>
...

Ressources disponibles

Chaque ressource API exposée par la CLI est documentée dans la référence API. Pour une liste locale, exécutez ant --help, et ajoutez --help à n'importe quelle sous-commande pour afficher ses options et paramètres.