ii999/agentenv

Was macht agentenv?

agentenv liest eine lokale TOML-Konfigurationsdatei, die gewöhnliche Werte und Verweise auf Anmeldeinformationen enthält. Die Werte der Anmeldeinformationen befinden sich in einer Umgebungsvariablen, im plattformeigenen Credential Store oder in einem externen Befehl – niemals in der Datei. Die CLI liest Werte, bearbeitet die Datei mit validierten, formatbewahrenden Schreibvorgängen und startet Zielprozesse mit ausgewählten, in eine temporäre Umgebung injizierten Werten.

Stelle sicher, dass die CLI mit command -v agentenv verfügbar ist, bevor du sie verwendest. Falls sie fehlt, sage dies und stoppe; rekonstruiere ihr Verhalten nicht, indem du die Konfigurationsdatei direkt liest.

Harte Regeln

• Gib niemals einen aufgelösten Wert einer Anmeldeinformation aus, protokolliere oder fasse ihn zusammen. Starte agentenv run nicht mit einem Ziel, das darauf ausgelegt ist, seine eigene Umgebung preiszugeben – env, printenv, set, sh -c 'echo $VAR' oder das Schreiben der Umgebung in eine Datei sind alles Verstöße.
• Schreibe niemals einen geheimen Wert in die Konfigurationsdatei. set ist für gewöhnliche Werte; credential add schreibt nur eine Definition; credential set ist der einzige Pfad, der einen Wert speichert, und er speichert ihn im plattformeigenen Credential Store, nicht in der Datei.
• Wenn ein Profil, Eintrag, Feld oder eine Anmeldeinformation fehlt, melde dies explizit. Rate keinen Feldnamen, wechsle nicht stillschweigend das Profil oder ersetze eine andere Anmeldeinformation.
• Lies die Konfiguration über die CLI, nicht durch Öffnen der TOML-Datei, damit Profilauswahl, Credential-Indirektion und Validierung angewendet werden.
• Wenn credential fill einen Wert in ein Browserfeld schreibt, lies dieses Feld nicht zurück, werte seinen Wert nicht aus und mache keinen Screenshot, der es zeigt. Das Ausfüllergebnis ist das Einzige, was du melden darfst.

Konfiguration lesen

Gehe von oben nach unten vor; überspringe Schritte, die du in dieser Sitzung bereits durchgeführt hast.

1. agentenv project status --json – Finde die nächstgelegene Projektdatei und ihren Vertrauensstatus, bevor du profilabhängige Konfiguration liest. Der Bericht wird auf stdout geschrieben, auch wenn der Exit-Code 5 oder 6 ist; ein Exit-Code 2 hinterlässt stdout leer.
2. agentenv list --json – Finde Profile und Einträge. agentenv list --profiles listet Profilnamen, ohne eines auszuwählen.
3. agentenv show <eintrag> --json – Untersuche einen unbekannten Eintrag, bevor du ihn verwendest. Felder mit Anmeldeinformationen erscheinen als reference-Element (credential://<name> oder credential://<name>?as=<ENV>), niemals als Wert.
4. agentenv get <pfad> – Lese einen gewöhnlichen Skalarwert. Verwende --json für ein Array oder eine Tabelle. Das Lesen eines Credential-Feldes gibt die Referenzzeichenfolge zurück, nicht das Geheimnis.
5. agentenv find <suchbegriff> --json – Durchsuche Eintragsnamen, Feldnamen, Beschreibungen und Zeichenfolgenwerte, wenn du nicht weißt, wo etwas lebt. Füge --all-profiles hinzu, um jedes Profil zu durchsuchen.

Pfade sind punktgetrennte Feldsegmente innerhalb des ausgewählten Profils, z. B. llm.model. Setze ein Segment, das Satzzeichen oder Leerzeichen enthält, in Anführungszeichen: servers."mein host".port. Das Profil ist nicht Teil des Pfads; wähle es mit --profile <NAME> (Priorität: --profile, dann AGENTENV_PROFILE, dann der vertrauenswürdige Projekt-Pin, dann default_profile in der Datei). Dies gilt für Lesevorgänge, run, set und unset. --create-profile erfordert ein explizites --profile und verwendet niemals den Pin.

Projektbezogene Konfiguration

agentenv findet die nächstgelegene reguläre .agentenv.toml-Datei, während es vom Arbeitsverzeichnis zur Dateisystemwurzel aufsteigt. Die Datei hat ein geschlossenes, auswahlbasiertes Schema: version = 1, ein optionales nicht leeres profile und optionale [requires.<eintrag>]-Tabellen mit einer nicht leeren reason und optionalen eintragsbezogenen fields, die, falls vorhanden, nicht leer sind. Sie ist auf 64 KiB begrenzt und darf keine Werte, Credential-Definitionen, inject-Tabellen oder credential://-Zeichenfolgen enthalten.

Projektdateien sind inaktiv, bis ihr genauer Inhalt genehmigt wurde. Verwende agentenv project status, agentenv project allow und agentenv project revoke, um den Status zu überprüfen, zu genehmigen und die Genehmigung zu entziehen. Die Genehmigung wird im Benutzerzustandsverzeichnis außerhalb des Repositorys aufbewahrt; das Bearbeiten der Datei macht sie wieder ungültig. Eine nicht vertrauenswürdige Datei beeinflusst keinen gewöhnlichen Befehl, abgesehen von einem Hinweis auf stderr.

Verwende --no-project oder eine nicht leere AGENTENV_NO_PROJECT, um die Suche für einen Befehl außerhalb der project-Gruppe zu umgehen. Die Umgehung gilt niemals für project status, project allow oder project revoke, die immer die nächstgelegene Datei finden.

project status --json schreibt seinen Bericht absichtlich auf stdout mit Exit-Code 5 für einen nicht verfügbaren, ungültigen oder nicht vertrauenswürdigen Projektzustand und mit Exit-Code 6, wenn Anforderungen nicht erfüllt oder nicht überprüfbar sind. Dies ist die Ausnahme zur üblichen Regel des leeren stdout bei fehlschlagendem JSON. Exit-Code 2 deckt Konfigurationsfehler ab, einschließlich Validierungsfehler der Projektdatei, und hinterlässt stdout für diesen Befehl leer.

Ausführen eines Befehls, der Anmeldeinformationen benötigt

Verwende run mit einem oder mehreren --with <eintrag>-Flags und dem Ziel nach --:

agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync

Jeder --with-Eintrag liefert seine Credential-Referenzen und seine inject- Tabelle (die Umgebungsnamen auf gewöhnliche Felder dieses Eintrags abbildet). Eine Anmeldeinformation wird unter ihrem inject_as-Namen injiziert, es sei denn, die Referenz trägt eine ?as=<ENV>-Überschreibung. Um zu erfahren, welche Umgebungsnamen ein Ziel erhalten wird, lies inject_as aus agentenv credential list --json und die inject-Tabelle und reference- Elemente aus agentenv show <eintrag> --json.

Die stdin/stdout/stderr des Ziels werden unverändert durchgereicht und sein Exit-Code wird zurückgegeben. Konflikte bei der Injektion (zwei Quellen, die auf einen Umgebungsnamen abzielen) brechen mit Exit-Code 4 ab, bevor etwas aufgelöst oder gestartet wird.

Füge --pure hinzu, um das Ziel mit einer kuratierten Minimalumgebung zu starten: eine feste Plattformbasis (PATH, HOME, Locale, AGENTENV_* und ähnliche prozesskritische Namen), plus explizit mit dem wiederholbaren --keep <NAME> getragene Variablen, plus die Injektionen – nichts anderes aus der aufrufenden Shell. Ein in der Elternshell nicht gesetzter gehaltener Name wird auf stderr gemeldet und der Lauf fortgesetzt. --pure filtert nur die Umgebung des Ziels; es ist keine Sandbox, und verschachtelte agentenv-Aufrufe innerhalb des Ziels lösen immer noch dieselbe Konfiguration auf. Die Credential-Auflösung wird durch --pure nicht geändert: ein Unterprozess eines command-Providers behält die vollständige Elternumgebung.

Konfiguration schreiben

Verwende diese, wenn der Benutzer fragt, Konfiguration aufzuzeichnen:

agentenv init                            # Erstelle die Konfigurationsdatei; verweigert das Überschreiben
agentenv set <pfad> <wert>              # Schreibe einen Wert; erstellt Zwischentabellen
agentenv set <pfad> <wert> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "Standard-LLM."   # Erstellt auch den Eintrag
agentenv set <pfad> <wert> --profile dev --create-profile "Dev-Profil."
agentenv unset <pfad>                    # Entferne ein Feld oder eine Tabelle

Jeder Eintrag benötigt eine Beschreibung; das Erstellen eines neuen Eintrags der obersten Ebene erfordert --description beim selben set. Ein unbekanntes Profil ist ein Fehler, es sei denn, du übergibst --create-profile mit einem expliziten --profile. Jeder Schreibvorgang wird zuerst dateiweit validiert und abgelehnt, wenn das Ergebnis ungültig wäre. Ein abgelehnter Schreibvorgang lässt die Datei byte-identisch – melde die Diagnose, anstatt blind Variationen zu wiederholen.

Die Validierung verweigert Klartextwerte in Zeichenfolgenfeldern, die token, password, secret, api_key oder private_key heißen oder so enden: solche Felder müssen eine credential://-Referenz enthalten. Wenn der Benutzer dir ein Geheimnis zum Speichern gibt, definiere und speichere es stattdessen als Anmeldeinformation (nächster Abschnitt) und verweise darauf.

Verwalten von Anmeldeinformationen

agentenv credential list --json          # Definitionen + flacher Status; löst nichts auf
agentenv credential check <name>         # Löst eine Anmeldeinformation auf; meldet nur Verfügbarkeit
agentenv credential add <name> --description "<text>" --provider env \
    --env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider keychain \
    --service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider command \
    --argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json  # Öffne lokalen Eintrag; warte auf sein Ergebnis

Reihenfolge für eine neue Anmeldeinformation: credential add die Definition, dann für den Keychain-Provider speichere den Wert mit credential set, dann verweise darauf von einem Eintragsfeld als credential://<name>. Env- und Command-Anmeldeinformationen beziehen ihre Werte aus ihren externen Systemen; credential set gilt nicht für sie.

Starte für den lokalen Keychain-Eintrag credential set <name> --input dialog --json ohne PTY. Sage dem Benutzer, den Wert im lokalen Fenster einzugeben und zu speichern. Lasse den Befehl laufen und warte auf seinen Abschluss, auch über ein Tool-Session-Yield hinweg; ein offenes Fenster ist kein abgeschlossener Speichervorgang. Untersuche, erfasse, lese oder automatisiere niemals das live-Eingabefenster oder die Zwischenablage. Der Benutzer gibt den Wert dort ein und überprüft ihn, und der Befehl gibt nur Abschlussmetadaten zurück.

Setze die abhängige Aufgabe erst nach Exit-Code 0 und JSON status: "stored" fort. status: "cancelled" bedeutet, dass der Eintrag ohne bestätigte Speicherung endete; melde es und stoppe die abhängige Aktion. status: "failed" enthält einen nicht geheimen reason; melde die Diagnose. store-unconfirmed bedeutet, dass ein Schreibvorgang möglicherweise stattgefunden hat; behaupte daher nicht, dass der vorherige Wert unverändert ist, und wiederhole nicht automatisch. Start-/Konfigurationsfehler können beendet werden, bevor JSON ausgegeben wird; behandle einen Exit-Code ungleich null oder fehlendes Ergebnis als Fehler. Ein bereits laufender Speichervorgang wird abgeschlossen, bevor der Befehl zurückkehrt; ein bestätigter Schreibvorgang meldet stored, selbst wenn der Benutzer während dieses Schreibvorgangs die Schließung angefordert hat.

Der Dialog benötigt eine grafische Sitzung auf dem Rechner, der agentenv ausführt. Auf einem entfernten oder headless Host erkläre diese Einschränkung und lasse den Benutzer agentenv credential set <name> --input terminal selbst in diesem Host-Terminal ausführen und dann den Abschluss bestätigen. Ersetze keine agenteneigene PTY oder stdin-Pipe. Frage niemals nach dem Wert im Chat oder platziere ihn in argv, einer Umgebungsvariablen, einer Befehlspipe oder einer Datei. Die Terminaleingabe unterstützt einen lokalen Ein-/Ausblendbefehl, daher muss ihre Bildschirmausgabe außerhalb der Agent-Werkzeuge bleiben.

Bevorzuge keychain- oder command-Provider für die lokale Verwendung; env legt den Wert für jeden Prozess offen, der die Umgebung erbt, und eignet sich für CI.

Docker-Compose-Paarung

Halte nicht geheime Einstellungen in .env. Injiziere Anmeldeinformationen nur für den Prozess, der sie benötigt, und lasse dann Compose die injizierte Variable empfangen:

agentenv run --with llm -- docker compose up

services:
  app:
    image: alpine:3.20
    environment:
      - OPENAI_API_KEY

${OPENAI_API_KEY}-Interpolation wird ebenfalls von Compose unterstützt. Verwende keine env_file:, die Geheimnisse enthält; sie persistiert Anmeldeinformationen in einer Datei.

Ausfüllen einer Anmeldeinformation in ein Browserfeld

Verwende credential fill, wenn eine Seite, die du steuerst, eine gespeicherte Anmeldeinformation in einem Eingabefeld benötigt. Es schreibt den Wert über das Debugging-Protokoll des Browsers; du navigierst und sendest weiterhin mit deinem eigenen Browser-Werkzeug.

agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
    --page-url <exakte Seiten-URL> --selector '<CSS des einen Eingabefelds>' --json

Schritte:

1. Bestätige, dass --capabilities das cdp-Backend als verfügbar auflistet. Dein Browser muss einen Loopback-Chrome-DevTools-Protocol-Endpunkt bereitstellen (ein Chromium, gestartet mit --remote-debugging-port und einem nicht standardmäßigen --user-data-dir, oder der Endpunkt, den dein Browser-Werkzeug bereits verwendet). Wenn es keinen gibt, sage dies; starte keinen Browser und füge den Wert nicht ein.
2. Navigiere mit deinem Browser-Werkzeug zur Seite und übergib dann die exakte URL der Seite und einen CSS-Selektor, der nur das Ziel-Eingabefeld matcht. Füge --page-match origin-path hinzu, wenn die URL volatile Abfrageparameter trägt, --frame-selector für jedes iframe auf dem Weg zum Feld und --context-index, wenn dieselbe URL in mehreren Kontexten geöffnet ist.
3. Schließe DevTools auf diesem Tab und halte Tracing, Screencasts, HAR und Videoaufzeichnung während des Füllens ausgeschaltet; agentenv schlägt nur beim offenen DevTools-Fenster fehl, weil die anderen Rekorder nicht erkannt werden können.
4. Führe den Befehl aus. Bei Erfolg wird nur {"version":1,"backend":"cdp","effect":"field-filled"} ausgegeben; der vorherige Inhalt des Feldes wurde ersetzt und die Seite erhielt normale Eingabeereignisse. Fahre mit deinem eigenen Werkzeug fort, um abzusenden.

Nur Anmeldeinformationen, die die Nutzung in der environment erlauben, können ausgefüllt werden. Der Wert muss eine einzelne Zeile von maximal 8.192 Bytes ohne Steuer-, Zeilentrenn- oder bidirektionale Steuerzeichen sein (sonst value-unsupported). Ein Command-Provider läuft ohne Terminal und sein einziges abschließendes Newline wird entfernt; leere, NUL- oder nicht-UTF-8-Ausgabe des Providers ist ein Credential-Fehler (Exit 4). Der gesamte Vorgang, einschließlich eines Keychain-Autorisierungsdialogs beim ersten Zugriff, läuft unter --timeout-ms (Standard 30.000); erhöhe ihn, wenn der Benutzer durch einen solchen Dialog klicken muss. credential fill überprüft das Feld nicht, sendet das Formular nicht ab und meldet sich nicht an; melde den Effekt, keinen Erfolg, den du nicht beobachtet hast.

Fehlerursachen auf stderr (credential-fill: <grund>: <nachricht>). Exit 8, nichts geändert: backend-unavailable, permission, connect-failed, version-unsupported, recording-conflict, context-absent, page-absent, page-ambiguous, frame-absent, frame-ambiguous, frame-invalid, target-absent, target-ambiguous, target-hidden, target-disabled, target-readonly, target-unfillable, target-changed, value-unsupported, timeout, cancelled. Exit 11, das Feld könnte den Wert enthalten: timeout, cancelled oder delivery-failed, nachdem der Wert gesendet wurde, und cleanup-unconfirmed nach einem zugestellten Wert.

Privilegierte Ausführung

Wenn die Anfrage ein konfiguriertes sudo-target verwendet, lies references/sudo-execution.md, bevor du planst, überprüfst, ausführst, erstellst oder rotierst dieses Ziel.

…

[Hinweis: Die Originaldatei wurde nach "privileged execution" abgeschnitten; die Übersetzung folgt diesem abgeschnittenen Inhalt.]