--- title: "Kommandozeile" source: "https://ayoune.com/de/docs/cli" tenant: "tolinax UG" brand: "aYOUne" collection: "Kommandozeile" language: "de" retrieved: "2026-09-11T15:40:51.058Z" summary: "Referenz und Anleitungen zur aYOUne-CLI." platform: "aYOUne — https://ayoune.com" generator: "aYOUne Doku-Export" contact: "info@tolinax.com" license: "Alle Rechte vorbehalten. Weitergabe nur mit Quellenangabe." --- # Kommandozeile Referenz und Anleitungen zur aYOUne-CLI. _139 Seiten in dieser Sammlung._ ## aYOUne CLI Überblick # aYOUne CLI Überblick Die aYOUne CLI (`ay`) ist das offizielle Kommandozeilen-Werkzeug für die aYOUne-Plattform. Sie liefert direkten Zugriff auf alle ~602 Collections, die Deployment-Pipeline, Custom Functions und das lokale Self-Hosting — aus jedem Terminal, ohne Browser. ## Wofür - **Datenzugriff:** Jede Collection lesen, schreiben, durchsuchen, aggregieren. - **Automatisierung:** Exports, Batch-Updates, scheduled Scripts. - **DevOps:** Deployments, Logs, Pipeline-Status, Cluster-Health. - **FaaS:** Custom-Functions lokal entwickeln, deployen, invoken. - **Self-Hosting:** Docker-Compose-Stacks starten/stoppen, Updates einspielen. ## Schnellstart ```bash npm install -g @tolinax/ayoune-cli ay setup # Interaktiver First-Run-Wizard ay login # Authentifizierung via Browser ay list consumers # Erste Abfrage ``` Siehe [Installation](wiki:cli/install) und [Erster Login](wiki:cli/login) für Details. ## Struktur dieser Dokumentation - **[Einstieg](wiki:cli/getting-started)** — Installation, Setup, First-Run-Tutorial - **[Konzepte](wiki:cli/concepts/authentication)** — Auth, Customer-Context, Output-Formate - **[Befehle](wiki:cli/commands)** — Vollständige Referenz aller 45 Commands, gruppiert - **[Rezepte](wiki:cli/recipes)** — Häufige Workflows - **[Problembehebung](wiki:cli/troubleshooting)** — Fehler, Debugging, bekannte Probleme ## Version Aktuelle CLI-Version: `@tolinax/ayoune-cli@2026.17.0`. ::: info Die CLI verwendet CalVer (Calendar Versioning) im Format `YYYY.MINOR.PATCH`. ::: --- ## Installation # Installation Die aYOUne CLI wird als npm-Paket verteilt und läuft auf Node.js ≥ 20. ## Voraussetzungen - **Node.js ≥ 20** (empfohlen: aktuelle LTS). - **npm ≥ 10** oder **pnpm ≥ 8** oder **yarn ≥ 4**. - Eine aYOUne-Tenant-Zugehörigkeit (Login erforderlich für fast alle Commands). ## Global installieren ```bash npm install -g @tolinax/ayoune-cli ``` Nach erfolgreicher Installation steht das Binary `ay` im Path zur Verfügung: ```bash ay --version # 2026.17.0 ``` ## Alternativen ### Ohne globale Installation ```bash npx @tolinax/ayoune-cli login ``` ### pnpm ```bash pnpm add -g @tolinax/ayoune-cli ``` ### yarn ```bash yarn global add @tolinax/ayoune-cli ``` ## Shell-Completion ```bash # Bash ay completions bash > ~/.ayoune-completion.bash echo "source ~/.ayoune-completion.bash" >> ~/.bashrc # Zsh ay completions zsh > ~/.ayoune-completion.zsh echo "source ~/.ayoune-completion.zsh" >> ~/.zshrc # Fish ay completions fish > ~/.config/fish/completions/ay.fish ``` ## Update ```bash npm install -g @tolinax/ayoune-cli@latest ``` ::: tip Im Umfeld des Monorepos entspricht die CLI-Version der aktuellen Platform-Version. Prüfe regelmäßig auf Updates, um neue Commands und Bugfixes zu bekommen. ::: ## Nächster Schritt [Erst-Setup durchführen](wiki:cli/setup) — interaktiver Wizard, der Customer-Context, Default-Output-Format und Auth konfiguriert. --- ## Erst-Setup # Erst-Setup Der Befehl `ay setup` ist ein interaktiver Wizard, der alle wichtigen Einstellungen einmalig erfasst und in `~/.config/ayoune/config.json` speichert. ## Aufruf ```bash ay setup ``` ## Was der Wizard abfragt 1. **API-Host** — Default `api.ayoune.app`. Für Self-Hosting: eigene Domain. 2. **Auth-Host** — Default `auth.ayoune.app`. 3. **Default-Customer-Context** — falls du Zugriff auf mehrere Tenants hast, hier die primäre Auswahl. 4. **Default-Output-Format** — `json`, `yaml`, `table`, `csv`. 5. **Editor für `ay edit`** — `code`, `vim`, `nano`, `$EDITOR` (fallback). 6. **Locale** — `de` oder `en`, beeinflusst Fehlermeldungen und Help-Texte. ## Manuelle Konfiguration Ohne Wizard direkt die Config-Datei bearbeiten: ```bash ay config set apiHost api.ayoune.app ay config set defaultFormat yaml ay config set editor vim ay config get # aktuelle Config zeigen ``` Config-File-Ort: `~/.config/ayoune/config.json` (XDG-konform). ## Nächster Schritt [Erster Login](wiki:cli/login) — Browser-basierte Authentifizierung gegen `auth.ayoune.app`. --- ## Authentifizierung # Authentifizierung Die meisten CLI-Befehle erfordern eine aktive Session. Die CLI nutzt `auth.ayoune.app` mit OAuth2-PKCE-Flow im Browser. ## Anmelden ```bash ay login ``` Der Befehl öffnet automatisch den Default-Browser auf `https://auth.ayoune.app/?continue=...`. Nach erfolgreicher Anmeldung wird das JWT lokal in `~/.aYOUne/storage/` abgelegt und automatisch alle 55 Minuten erneuert. ## Aktuellen User anzeigen ```bash ay whoami ``` Zeigt: User-ID, Email, aktiver Customer-Context, Rechte-Scope. ## Customer-Context wechseln Bei Multi-Tenant-Zugehörigkeit: ```bash ay switch # interaktiver Picker ay switch customer # direkt ay switch back # zum vorherigen Context zurück ay switch current # aktuellen Context anzeigen ay switch list # alle verfügbaren Tenants ``` ::: info Der Customer-Context bestimmt das `_customerID`-Scoping jeder nachfolgenden Query. `ay list consumers` zeigt NUR Consumers des aktiven Tenants. ::: ## Abmelden ```bash ay logout # Token löschen ``` ## Token-Storage inspizieren ```bash ay storage set # Einzelnen Wert setzen ay storage clear # Kompletten Storage leeren (forced logout) ``` ## Troubleshooting - **"Login Browser öffnet sich nicht"** — Manuell zu `https://auth.ayoune.app/?continue=http://localhost:{port}` navigieren (Port wird im Terminal ausgegeben). - **"Session expired"** — CLI refreshed JWT alle 55min. Wenn das Gerät länger offline war, `ay login` erneut ausführen. - **"No access to customer"** — `ay whoami` prüfen, ggf. `ay switch list` und korrekten Context wählen. ## Nächster Schritt [First-Run-Tutorial](wiki:cli/first-run-tutorial) — die ersten fünf produktiven Befehle. --- ## First-Run-Tutorial # First-Run-Tutorial Nach [Install](wiki:cli/install), [Setup](wiki:cli/setup) und [Login](wiki:cli/login): die fünf ersten produktiven Befehle. ## 1. Module erkunden ```bash ay modules ``` Interaktive Übersicht aller 25 Module (CRM, Marketing, CMS, DevOps, …) mit ihren Collections. Navigiere mit Pfeiltasten, öffne eine Collection mit Enter. ## 2. Erste Abfrage ```bash ay list consumers --limit 5 --format table ``` Zeigt die letzten 5 Consumers als Tabelle. Flags: - `--limit N` — Ergebnis-Anzahl - `--format json|yaml|table|csv` — Output-Format - `--sort createdAt:-1` — Sortierung ## 3. Einen einzelnen Datensatz holen ```bash ay get consumers 64a1b2c3d4e5f60012345678 ``` Liefert den kompletten Consumer-Datensatz. Mit `-f yaml` für besser lesbares Format. ## 4. Eintrag erstellen ```bash ay create projects "Neues Pilotprojekt" ``` Legt ein `Projects`-Dokument mit `name: "Neues Pilotprojekt"` an und gibt die neue ID zurück. Weitere Felder via `--set field=value`. ## 5. Aggregation ausführen ```bash ay aggregate wizard ``` Interaktiver Wizard, der Collection, Pipeline-Stages und Output-Optionen Schritt-für-Schritt abfragt und am Ende das MongoDB-Pipeline-JSON + den ausgeführten Output zeigt. Gute Einstiegs-Lernkurve für Aggregations-Arbeit. ## Was als Nächstes - [Konzept: Customer-Context](wiki:cli/concepts/customer-context) — Multi-Tenant-Grundlagen. - [Konzept: Output-Formate](wiki:cli/concepts/output-formats) — wann JSON vs YAML vs Table. - [Befehlsreferenz](wiki:cli/commands) — alle 45 Commands, gruppiert. ::: tip Tipp Mit `ay --help` oder `ay --help` bekommst du jederzeit Inline-Hilfe. ::: --- ## Authentifizierung # Authentifizierung Die CLI nutzt denselben Auth-Flow wie alle anderen aYOUne-Clients: OAuth2-PKCE gegen `auth.ayoune.app`, JWT-Tokens mit 60-Minuten-Lifetime und automatischem Refresh 5 Minuten vor Ablauf. ## Flow 1. `ay login` startet einen lokalen HTTP-Listener auf einem freien Port. 2. Browser öffnet `https://auth.ayoune.app/?continue=http://localhost:{port}&code_challenge=...`. 3. Nach Login redirected der Auth-Service mit `?code=...` zurück auf den Listener. 4. CLI tauscht Code gegen `{ accessToken, refreshToken }` via `/oauth/token`. 5. Tokens werden in `~/.aYOUne/storage/tokens.json` abgelegt (OS-Dateirechte `0600`). ## Token-Lifecycle | Token | TTL | Refresh | |---|---|---| | `accessToken` | 60 min | Automatisch 55min nach Ausstellung | | `refreshToken` | 30 Tage | Nur beim Re-Login erneuert | Wenn der Refresh fehlschlägt (z.B. Refresh-Token expired), wird der User zum erneuten `ay login` aufgefordert. ## Service-Accounts (Headless) Für CI/CD + scheduled Scripts: API-Keys statt Browser-Login. ```bash ay login --api-key $AYOUNE_API_KEY ``` API-Keys werden pro Customer im Admin-UI angelegt (`mobile-app → Einstellungen → Integrationen → API-Keys`). Sie haben dieselben Rechte wie der erzeugende User und können widerrufen werden. ## Rechte-Scope Die CLI respektiert die serverseitigen Rechte-Gates (`..`, z.B. `crm.consumers.read`). Unzureichende Rechte resultieren in HTTP-403 mit klarer Meldung. Prüfen, welche Module dem aktiven User zugänglich sind: ```bash ay access ``` ## Siehe auch - [First-Run-Tutorial](wiki:cli/first-run-tutorial) - [Customer-Context](wiki:cli/concepts/customer-context) --- ## Customer-Context # Customer-Context aYOUne ist multi-tenant. Fast jede Collection hat ein `_customerID`-Feld, das den Zugriff scoped. Die CLI hält einen aktiven **Customer-Context** pro Session vor. ## Aktiven Context anzeigen ```bash ay whoami # zeigt auch aktiven Customer ay switch current # fokussiert nur auf Customer ``` Die Terminal-Prompt-Integration (`ay prompt`, optional) zeigt den aktiven Customer als Präfix, z.B. `[tolinax] $`. ## Context wechseln ```bash ay switch # interaktiver Picker (Tabelle mit Slug, Name, Role) ay switch customer tolinax # direkt via Customer-Slug ay switch customer 64a1b2c3d4e5... # direkt via Customer-ID ay switch back # zurück auf vorherigen Context ay switch list # alle verfügbaren Tenants ``` Der neue Context persistiert bis zum nächsten `ay switch` oder `ay logout`. ## Auswirkung auf Abfragen - **List/Get/Search/Aggregate** filtern immer nach `_customerID = activeContext`. - **Create** setzt `_customerID = activeContext` implizit. - **Update/Delete** prüfen serverseitig, dass das Target-Dokument dem aktiven Customer gehört — sonst HTTP-403. ::: warning Achtung Bei `ay export` + `ay batch` ohne explizites `--customer`-Flag wird der aktive Context verwendet. Prüfe vor großen Operationen mit `ay whoami`. ::: ## Platform-Operator-Modus Tolinax-Mitarbeiter mit `restrictApiSuperUser`-Recht können in den Platform-Scope wechseln: ```bash ay switch customer platform ``` Im Platform-Scope sehen/ändern sie Cross-Tenant-Daten (Registry, Infra-Config, Diagnostik). Siehe auch [api-superuser-home](reference:api-superuser-home). ## Siehe auch - [Authentifizierung](wiki:cli/concepts/authentication) - [Permissions-Befehl](wiki:cli/auth-config) --- ## Output-Formate # Output-Formate Fast jeder CLI-Befehl akzeptiert `--format` (alias `-f`). Der Default ist via `ay setup` / `ay config set defaultFormat` einstellbar. ## Verfügbare Formate | Format | Flag | Einsatz | |---|---|---| | `json` | `-f json` | Maschinen-lesbar, für Pipes in `jq` etc. | | `yaml` | `-f yaml` | Menschen-lesbar, Default für `ay describe` + `ay edit` | | `table` | `-f table` | Terminal-Übersicht, ASCII-Grid, gekürzte Spalten | | `csv` | `-f csv` | Export für Excel / Tabellen-Tools | ## Nur Payload (ohne Envelope) ```bash ay list consumers -m # entfernt { payload, meta }-Wrapper ay get consumers -m # nur das Consumer-Objekt ``` ## Pipe-Beispiele ```bash # Alle Consumer-Emails extrahieren ay list consumers -f json -m | jq -r '.[].email' # CSV-Export direkt in Datei ay list orders -f csv > orders.csv # YAML-Diff zwischen zwei IDs diff <(ay get consumers A -f yaml) <(ay get consumers B -f yaml) ``` ## Farbausgabe - `--no-color` deaktiviert ANSI-Color-Codes. - `FORCE_COLOR=1` erzwingt Farben auch in Pipes. - `NO_COLOR=1` (Unix-Standard) respektiert die CLI. ## Fortschrittsausgabe Lang laufende Operationen (`ay export`, `ay batch`, `ay db pull`) zeigen Spinner + Fortschrittsbalken. In nicht-TTY-Umgebungen (CI-Logs) fallen sie auf statische Log-Lines zurück. ## Siehe auch - [First-Run-Tutorial](wiki:cli/first-run-tutorial) - [Aggregate-Befehl](wiki:cli/queries) --- ## Befehls-Referenz # Befehls-Referenz Die CLI bündelt 45 Commands in 8 logische Gruppen. Jede Gruppe hat eine eigene Landing-Page mit Überblick + Details zu den einzelnen Befehlen. ## Gruppen | Gruppe | Anzahl | Zweck | |---|---|---| | [CRUD & Core](wiki:cli/crud-core) | 12 | Daten lesen, erstellen, ändern, löschen | | [Queries & Analysis](wiki:cli/queries) | 5 | Search, Aggregate, Export, Batch, Access | | [Streaming & Events](wiki:cli/streaming) | 2 | Live-Updates, Platform-Events | | [Auth & Config](wiki:cli/auth-config) | 8 | Login, Switch, Context, Setup, Config, Alias | | [Folder-based](wiki:cli/folder-based) | 3 | `local`, `functions`, `provision` mit Subcommands | | [DevOps & Deployment](wiki:cli/devops) | 7 | `deploy`, `monitor`, `status`, `db`, `release`, `pm`, `self-host-update` | | [Utilities](wiki:cli/utilities) | 5 | `actions`, `exec`, `ai`, `services`, `webhooks` | | [Miscellaneous](wiki:cli/misc) | 3+ | `jobs`, `users`, `sync`, `permissions`, `templates`, `credentials`, `rdp`, `doctor`, `completions` | ## Globale Flags Jeder Command akzeptiert: | Flag | Zweck | |---|---| | `--help` / `-h` | Inline-Hilfe zum Command | | `--format` / `-f` | Output-Format: json, yaml, table, csv | | `--no-color` | Deaktiviert Farbausgabe | | `--verbose` / `-v` | Mehr Log-Details | | `--quiet` / `-q` | Unterdrückt nicht-Fehler-Output | | `--customer ` | Override aktivem Customer-Context für diesen Call | ## Inline-Hilfe ```bash ay --help # Alle Commands ay --help # Command-Details ay --help # Subcommand-Details ``` ## Aliase Viele Commands haben Kurzformen (z.B. `l` für `list`, `g` für `get`). Siehe jede Command-Seite für die aktuellen Aliase. --- ### CRUD & Core # CRUD & Core Die 12 Basis-Commands für Daten-Zugriff auf alle Collections der Plattform. ## Commands | Command | Alias | Zweck | |---|---|---| | [list](wiki:cli/crud-core/list) | `l` | Liste einer Collection mit Paginierung | | [get](wiki:cli/crud-core/get) | `g` | Einzelner Datensatz via ID | | [create](wiki:cli/crud-core/create) | `c` | Neuen Datensatz anlegen | | [edit](wiki:cli/crud-core/edit) | `e` | Datensatz im Editor öffnen | | [copy](wiki:cli/crud-core/copy) | `cp` | Datensatz duplizieren | | [delete](wiki:cli/crud-core/delete) | `rm` | Datensatz per ID löschen | | [update](wiki:cli/crud-core/update) | `u` | Einzelne Felder aktualisieren | | [describe](wiki:cli/crud-core/describe) | `d` | Schema + YAML-View | | [storage](wiki:cli/crud-core/storage) | `s` | Token- & Prefs-Speicher | | [audit](wiki:cli/crud-core/audit) | `history` | Audit-Trail eines Docs | | [modules](wiki:cli/crud-core/modules) | `m` | Interaktive Modul/Collection-Browser | | [upload](wiki:cli/crud-core/upload) | — | File-Upload nach Documents | ## Gemeinsames Pattern Alle CRUD-Commands erwarten als erstes Argument die **Collection** (lowercased plural aus `modelsAndRights.ts`, z.B. `consumers`, `products`, `orders`), und — wo sinnvoll — als zweites die **ObjectId** bzw. ein Name/Slug. ## Beispiele ```bash ay list consumers # Liste ay list consumers --limit 50 --sort 'createdAt:-1' ay get products 64a1b2c3d4e5f60012345678 # Einzeldatensatz ay create projects "Neues Projekt" # anlegen ay update tasks --set status=done # partielles Update ay delete logs # löschen ``` ## Siehe auch - [Konzept: Output-Formate](wiki:cli/concepts/output-formats) - [Befehl: list](wiki:cli/crud-core/list) --- #### ay list # `ay list` (Alias: `l`) Listet Dokumente einer Collection mit Paginierung, Sortierung und optionalen Filtern. ## Syntax ``` ay list [flags] ``` ## Flags | Flag | Default | Zweck | |---|---|---| | `--limit N` | 20 | Anzahl Ergebnisse pro Page | | `--skip N` | 0 | Offset | | `--sort :<-1\|1>` | `createdAt:-1` | Sortierung | | `--filter ''` | `{}` | MongoDB-Filter-Objekt | | `--fields ''` | alle | Projection | | `--format` | config-default | `json` / `yaml` / `table` / `csv` | | `-m` / `--minimal` | false | Nur Payload, kein `{payload, meta}`-Envelope | ## Beispiele ```bash # Einfache Liste mit 5 Einträgen ay list consumers --limit 5 # Gefiltert, nur ausgewählte Felder ay list orders \ --filter '{"status":"paid","total":{"$gte":100}}' \ --fields '{"_id":1,"total":1,"consumer":1}' \ --sort 'createdAt:-1' \ --limit 10 # Export zu CSV ay list invoices -f csv -m > invoices.csv ``` ## Paginierung Bei mehr als `--limit` Treffern zeigt die CLI: ``` Showing 20 of 1347 matching docs (page 1 of 68) Next page: ay list consumers --skip 20 ``` ## Performance-Tipp ```bash ay list --no-sort # schnellster Path, überspringt Sortier-Stage ay list --skip-count # kein Total-Count (schneller bei großen Collections) ``` ## Fehlerfälle - **HTTP 403** — Keine Rechte auf Collection. Via `ay access` prüfen. - **HTTP 404** — Collection existiert nicht. `ay modules` für korrekten Namen. - **Filter-Syntax-Error** — JSON muss valide sein; bei Shell-Escaping-Problemen via Heredoc oder File. ## Siehe auch - [get](wiki:cli/crud-core/get) — einzelner Datensatz - [search](wiki:cli/queries/search) — Volltextsuche --- #### ay get # `ay get` (Alias: `g`) Liest Datensätze aus einer Collection mit Feld-Selektion und Paginierung. Im Gegensatz zu `list` ist `get` für Field-Projection und tabellarische Ausgabe optimiert. ## Syntax ``` ay get [collection] [flags] ``` Erstes Argument ist entweder die Collection (z.B. `consumers`) oder das Modul (z.B. `crm`); im zweiten Fall folgt die Collection als zweites Argument. ## Flags | Flag | Default | Zweck | |---|---|---| | `-p, --page ` | 1 | Seite | | `-l, --limit ` | 20 | Einträge pro Seite | | `-f, --from ` | — | Ab-Datum (ISO 8601 oder `2026-04-01`) | | `-i, --fields ` | alle | Whitelist von Feldern (Projection) | ## Beispiele ```bash # Standard-Felder einer Collection ay get contacts # Explizites Modul ay get crm consumers # Nur ausgewählte Felder, Seite 3 ay get products -i name price stock -p 3 -l 10 # Als CSV speichern ay get orders -i _id total status createdAt -r csv --save ``` ## Siehe auch - [list](wiki:cli/crud-core/list) — Listen-Modus mit Filter - [search](wiki:cli/queries/search) — Volltextsuche - [describe](wiki:cli/crud-core/describe) — Schema eines Eintrags --- #### ay edit # `ay edit` (Alias: `e`) Öffnet einen einzelnen Eintrag im interaktiven CLI-Editor (Tabellen- oder Raw-JSON-Modus). Speichert beim Beenden via `PUT`. Gegenstück zu [update](wiki:cli/crud-core/update), das non-interaktiv arbeitet. ## Syntax ``` ay edit [collection] [id] ``` Beide Argumente fallen ohne Eingabe auf den zuletzt benutzten Wert (`lastCollection`, `lastId`) zurück. ## Verhalten `edit` ruft erst `GET //` auf und entscheidet dann: - Hat die Antwort `content.columns` (Tabellen-Schema) → **Tabellen-Editor** mit Inline-Editing pro Feld. - Sonst → **Raw-JSON-Editor** im Default-`$EDITOR`. ## Beispiele ```bash # Aktiven Eintrag editieren (lastCollection + lastId) ay edit # Konkreter Datensatz ay edit contacts 64a1b2c3d4e5f60012345678 # Alias ay e tasks 64a1b2c3 ``` ## Siehe auch - [update](wiki:cli/crud-core/update) — non-interaktiv für Scripts - [get](wiki:cli/crud-core/get) — nur lesen - [audit](wiki:cli/crud-core/audit) — Änderungs-History --- #### ay copy # `ay copy` (Alias: `cp`) Dupliziert einen Datensatz innerhalb einer Collection. Server-seitig: GET → neue _id → POST. Bei Sub-Documents werden nested IDs neu generiert. ## Syntax ``` ay copy [collection] [id] ``` Beide Argumente defaulten auf `lastCollection` / `lastId`. ## Beispiele ```bash # Konkreter Datensatz ay copy contacts 64a1b2c3d4e5f60012345678 # Letzten Eintrag duplizieren ay cp # Email-Template als Vorlage kopieren ay copy emailtemplates 6792... ``` ## Verhalten - Der Server vergibt eine neue `_id`. - `copiedFrom` wird auf die ursprüngliche `_id` gesetzt (sofern das Schema das Feld unterstützt). - Audit-Log wird automatisch geschrieben. - `_customerID` wird beibehalten — Cross-Tenant-Copy nur via [Marketplace-Install-Worker](wiki:cli/concepts/marketplace). ## Siehe auch - [create](wiki:cli/crud-core/create) — Neuanlage von Grund auf - [update](wiki:cli/crud-core/update) — Felder am Duplikat anpassen --- #### ay describe # `ay describe` (Alias: `d`) Zeigt die YAML-View eines Eintrags inkl. aller Felder. Gut für Schema-Inspektion und Sub-Resource-Extraction (Comments, Attachments, Worklogs). ## Syntax ``` ay describe [collection] [id] [subResource] ``` ## Argumente | Argument | Default | Zweck | |---|---|---| | `collection` | `lastCollection` | Collection-Name | | `id` | `lastId` | ObjectId | | `subResource` | — | Optionales Feld, z.B. `comments`, `attachments`, `worklogs` | ## Beispiele ```bash # Komplette YAML-Ausgabe ay describe contacts 64a1b2c3d4e5 # Sub-Resource extrahieren ay describe tasks 64a1b2c3d4e5 comments # Sub-Resource als JSON ay describe tasks 64a1b2c3d4e5 comments -r json # JMESPath-Filter ay describe tasks 64a1b2c3d4e5 --jq "subject" # Alias auf den letzten Eintrag ay d ``` ## Siehe auch - [get](wiki:cli/crud-core/get) — Tabellen-View - [audit](wiki:cli/crud-core/audit) — Änderungs-Log --- #### ay create # `ay create` (Alias: `c`) Legt einen neuen Datensatz mit einem Namen an. Für Felder über `name` hinaus → siehe [update](wiki:cli/crud-core/update) direkt im Anschluss. ## Syntax ``` ay create [collection] [name] ``` Wenn beide Argumente fehlen und das TTY interaktiv ist, fragt die CLI nach Collection und Name. ## Beispiele ```bash # Mit Namen direkt ay create contacts "John Doe" # Mit Alias ay c products "Widget" # Workflow: anlegen + sofort befüllen ay create projects "Website-Relaunch" ay update projects --set status=planning --set budget=15000 ``` ## Verhalten - Server-seitig: `POST /` mit Body `{ name: "" }`. - Default-Felder (`_customerID`, Timestamps, Access-Control) werden vom Backend gefüllt. - Audit-Log wird geschrieben. - Bei fehlendem Recht (`..create`) → HTTP 403, Exit-Code 5. ## Siehe auch - [update](wiki:cli/crud-core/update) — Folgefelder befüllen - [copy](wiki:cli/crud-core/copy) — Duplikat statt Neuanlage - [upload](wiki:cli/crud-core/upload) — Files in Documents --- #### ay update # `ay update` (Alias: `u`) Aktualisiert einen Eintrag non-interaktiv — gemacht für Scripts und AI-Agenten. Im Gegensatz zu `edit` öffnet `update` keinen Editor; die Änderungen kommen via `--set`, `--body`, `--body-file` oder `--body-stdin`. ## Syntax ``` ay update [collection] [id] [flags] ``` ## Flags | Flag | Default | Zweck | |---|---|---| | `--set ` | — | Einzelne Felder (wiederholbar) | | `--body ` | — | Komplettes Update als JSON-String | | `--body-file ` | — | JSON-Datei einlesen | | `--body-stdin` | — | JSON via stdin pipen | | `--merge` | false | GET → merge → PUT (existing fields bleiben erhalten) | `--set`-Werte werden auto-gecastet: `true`/`false` → boolean, `null` → null, Zahlen → number, Rest bleibt string. ## Beispiele ```bash # Einzelne Felder ay update contacts 64a1b2c3 --set firstName=Jane --set active=true # AWS-State eines Computing Entity ay update computingentities 64a1b2c3 --set ip=35.159.50.19 --set instanceId=i-019c... # JSON-Body ay update contacts 64a1b2c3 --body '{"firstName":"Jane","tags":["vip"]}' # Aus Datei ay update products 64a1b2c3 --body-file changes.json # Aus stdin echo '{"status":"active"}' | ay update contacts 64a1b2c3 --body-stdin # Merge-Mode (GET + spread + PUT) ay update tasks 64a1b2c3 --set done=true --merge ``` ## Siehe auch - [edit](wiki:cli/crud-core/edit) — interaktiver Editor - [batch](wiki:cli/utilities/batch) — Bulk-Updates - [exec](wiki:cli/utilities/exec) — Custom-Actions --- #### ay delete # `ay delete` (Alias: `rm`) Löscht einen oder mehrere Einträge per ID. Bei interaktivem TTY ist eine Bestätigung erforderlich; mit `--force` wird sie übersprungen. ## Syntax ``` ay delete [collection] [ids] [flags] ``` `ids` kann eine einzelne ObjectId oder eine kommaseparierte Liste sein. ## Flags | Flag | Default | Zweck | |---|---|---| | `--ids-stdin` | false | IDs aus stdin lesen (zeilen- oder kommagetrennt) | | `--force` | false | Confirmation-Prompt überspringen | ## Beispiele ```bash # Einzelner Datensatz ay delete contacts 64a1b2c3d4e5 # Force ohne Prompt ay rm contacts 64a1b2c3d4e5 --force # Mehrere IDs ay delete contacts id1,id2,id3 --force # Aus Pipeline (z.B. von ay search) ay search tasks "status=archived" -i _id -m | ay delete tasks --ids-stdin --force ``` ## Verhalten - Bei mehreren IDs wird sequenziell gelöscht; Erfolg/Fehler-Counter am Ende. - Bei mindestens einem Fehler → Exit-Code 1. - `--force` ist Pflicht in non-TTY-Kontexten (CI, Pipes). ## Siehe auch - [batch delete](wiki:cli/utilities/batch) — Bulk-Variante mit detailliertem Reporting - [search](wiki:cli/queries/search) — IDs zum Pipen finden --- #### ay storage # `ay storage` (Alias: `s`) Zeigt und verwaltet den lokalen CLI-Speicher: AES-256-CBC-verschlüsselte Tokens (`token`, `refreshToken`) und Klartext-Preferences (`lastModule`, `lastCollection`, `activeCustomerName`, …). Sensitive Werte werden in der Anzeige automatisch redacted (z.B. `eyJh••••5678`). Persistierung in `~/.aYOUne/storage/`. ## Syntax ``` ay storage # Show ay storage set # Set token | refreshToken ay storage clear # Remove token | refreshToken ``` ## Beispiele ```bash # Aktuellen Speicher inspizieren (redacted) ay storage # Token aus anderem Login persistieren ay storage set token eyJhbGciOi... # Token löschen (= sanftes Logout) ay storage clear token # Refresh-Token resetten ay storage clear refreshToken ``` ## Verhalten - `set` akzeptiert nur die Keys `token` und `refreshToken`. - Werte müssen valide JWT-Form haben (`
..`), sonst wird der Set abgelehnt. - Nicht-sensitive Keys (z.B. `lastCollection`) werden direkt gelesen, nicht entschlüsselt. ## Speicher-Order 1. `--token ` Flag (höchste Priorität) 2. `secureStorage.token` (dieser Befehl schreibt hierhin) 3. `AYOUNE_TOKEN` Environment-Variable (niedrigste Priorität) ## Siehe auch - [login](wiki:cli/cmd-login) — Browser-Login - [logout](wiki:cli/auth-config/logout) — Logout-Equivalent - [whoami](wiki:cli/auth-config/whoami) — Aktiven User anzeigen --- #### ay audit # `ay audit` (Alias: `history`) Zeigt den Änderungs-Verlauf eines Eintrags. Listet alle Audit-Records, ein interaktiver Picker öffnet den Detail-View des ausgewählten Records als YAML-Diff. ## Syntax ``` ay audit [collection] [id] ``` Beide Argumente defaulten auf `lastCollection` / `lastId`. ## Beispiele ```bash # History eines Consumers ay audit consumers 64a1b2c3d4e5 # History des letzten benutzten Eintrags ay history # History einer Task ay audit tasks 64a1b2c3 ``` ## Verhalten 1. CLI lädt die Audit-Liste (`GET ///audit`). 2. Interaktiver Picker zeigt Date + User + Action. 3. Bei Auswahl: Detail-Call (`GET ///audit/`) → YAML-Dump in Terminal. Audit-Records enthalten: - `_userID` — wer - `createdAt` — wann - `action` — `create` / `update` / `delete` - `before` / `after` — komplette Document-Snapshots ## Hinweis Der Befehl ist **interaktiv-only** — in Pipes oder CI funktioniert die Picker-Phase nicht. Für scriptbare Audit-Daten: `ay list audits --filter '{"_entityID":""}'`. ## Siehe auch - [describe](wiki:cli/crud-core/describe) — aktuellen YAML-State - [edit](wiki:cli/crud-core/edit) — Eintrag anpassen --- #### ay modules # `ay modules` (Alias: `m`) Interaktiver Browser für Module → Collections → Operationen. Auch nutzbar als Direkt-Mode mit positional args (analog zu `kubectl get`). ## Syntax ``` ay modules [module] [collection] [operation] [subject] [flags] ``` ## Operationen `list` · `get` · `create` · `delete` (alle anderen → siehe dedizierte Commands). ## Flags | Flag | Default | Zweck | |---|---|---| | `-p, --page ` | 1 | Seite (für list) | | `-l, --limit ` | 20 | Page-Size | | `-f, --from ` | — | Ab-Datum | | `-a, --all` | false | Alle Pages fetchen | | `-q, --search ` | — | Suchbegriff | ## Beispiele ```bash # Vollinteraktiver Browser ay modules # Direkt ins CRM-Modul ay m crm # CRM Consumers Collection ay m crm consumers # Direkt-Mode: Operation + Subject ay m pm projects list ay m pm projects create "Migration" ay m pm projects get 64a1b2c3 ay m pm projects delete 64a1b2c3 ``` ## Verhalten - Im Interactive-Mode werden nur die für den User accessible Module + Collections angezeigt. - Superuser sehen zusätzlich das `su`-Modul (57 System-Collections). - Module-Namen sind toleriert: `crm`, `CRM`, `Customer Relationship Management` matchen alle. ## Siehe auch - [access](wiki:cli/auth-config/access) — Was darf der User? - [list](wiki:cli/crud-core/list) — Direct-CRUD ohne Drilldown --- #### ay upload # `ay upload` Lädt eine lokale Datei in die `Documents`-Collection des aktiven Customers hoch. Pflicht ist eine Target-Entity, an die das Document gehängt wird. ## Syntax ``` ay upload --target [flags] ``` ## Flags | Flag | Default | Zweck | |---|---|---| | `-s, --state ` | `cms.downloads.edit` | Upload-Kontext / Access-Right | | `-t, --target ` | — (Pflicht) | ObjectId der Ziel-Entity | ## Beispiele ```bash # Software-Installer hochladen ay upload ./installer.exe \ --state cms.downloads.edit \ --target 698d574... # PDF einem Consumer-Datensatz anhängen ay upload ./report.pdf \ --state crm.documents.edit \ --target 507f1f7... # Receipt an Invoice ay upload ./receipt.pdf \ --state accounting.invoices.edit \ --target 64a1b2c3... ``` ## Verhalten - Multipart-POST gegen `config-api.ayoune.app/documents/upload`. - Server vergibt `_id`, schreibt File-Metadata + Storage-Pfad. - Antwort enthält `documentId`, `filename`, `size` — bei `--format json` kompletter Output. ## Fehlerfälle - **HTTP 403** — `--state` matched kein Right des Users. Via `ay access` prüfen. - **HTTP 413** — File > Customer-Quota. Customer-Limit hochsetzen. - **HTTP 422** — Target-Entity existiert nicht oder gehört anderem Customer. ## Siehe auch - [list documents](wiki:cli/crud-core/list) — `ay list documents` - [credentials](wiki:cli/folder-based/credentials) — für Cloud-Storage-Keys --- ### Queries & Analysis # Queries & Analysis 5 Commands für Volltextsuche, MongoDB-Aggregationen, Exports und Bulk-Operationen. ## Commands | Command | Alias | Zweck | |---|---|---| | [search](wiki:cli/queries/search) | `find` | Volltextsuche + Model-Search | | [aggregate](wiki:cli/queries/aggregate) | `agg` | MongoDB-Pipelines (7 Subcommands) | | [export](wiki:cli/queries/export) | `exp` | Datenexport mit Format-Wahl | | [batch](wiki:cli/queries/batch) | — | Bulk-Operationen | | [access](wiki:cli/queries/access) | — | Zugriffsrechte überblicken | ## Hero: `ay aggregate` `ay aggregate` ist der mächtigste Query-Command. Er öffnet einen Wizard oder führt vordefinierte Pipelines aus: ```bash ay aggregate wizard # Interaktiv ay aggregate run # Gespeicherte Pipeline ay aggregate exec --model Orders \ --pipeline '[{"$match":{"status":"paid"}},{"$group":{"_id":"$country","total":{"$sum":"$amount"}}}]' ``` Subcommands: `run`, `exec`, `list`, `save`, `validate`, `models`, `wizard`. ## Export-Beispiele ```bash ay export consumers --format csv --filter '{"active":true}' -o consumers.csv ay export orders --format json --date-range 2026-04-01..2026-04-30 ``` ## Siehe auch - [Konzept: Output-Formate](wiki:cli/concepts/output-formats) - [list](wiki:cli/crud-core/list) --- #### ay search # `ay search` (Alias: `find`) Volltextsuche und Field-Filter über aYOUne Search-Service. Vier Modi: 1. **Single-Model** — `ay search consumers "John"` (Default). 2. **Global SSE** — `ay search -g "John"` streamt Treffer aus allen Collections. 3. **FindOne** — `--one` gibt nur den ersten Treffer zurück. 4. **Legacy** — `--legacy` umgeht den Search-Service und nutzt das Module-API direkt (für Filter, die der Search-Index nicht unterstützt). ## Syntax ``` ay search [collectionOrModule] [collectionOrQuery] [query] [flags] ``` ## Flags | Flag | Default | Zweck | |---|---|---| | `-g, --global ` | — | SSE-Streaming über alle Collections | | `--field ` | — | Suche nur in einem Feld | | `--one` | false | Erster Treffer reicht | | `--legacy` | false | Module-API statt Search-Service | | `--filter ` | — | Field-Filter (`=`, `!=`, `>`, `<`, `>=`, `<=`) | | `--fields ` | — | Projection (kommagetrennt) | | `--sort ` | `-createdAt` | Sortierung (`-` für desc) | | `--count` | false | Nur Treffer-Anzahl ausgeben | | `-l, --limit ` | 25 | Page-Size | | `-p, --page ` | 1 | Seite | ## Beispiele ```bash # Volltext im Search-Index ay search consumers "John" ay search crm consumers "John" # Feld-spezifisch ay search consumers "John" --field firstName # Filter mit Operatoren ay search orders --filter "status=paid,total>500" ay search invoices --filter "createdAt>2026-04-01" --sort -total # Erster Treffer (FindOne) ay search consumers "Doe" --one --fields _id,firstName,lastName # Globale SSE-Suche ay search -g "tolinax" -l 50 # Nur zählen ay find tasks --filter "status=open" --count ``` ## Sanitizing `--fields` wird gegen `^-?[a-zA-Z_][a-zA-Z0-9_.$]*$` validiert — MongoDB-Operatoren (`$where`, `$gt`, …) werden abgelehnt. ## Siehe auch - [list](wiki:cli/crud-core/list) — primitive Listenanzeige - [aggregate](wiki:cli/queries/aggregate) — komplexe Pipelines - [export](wiki:cli/queries/export) — größere Datenmengen exportieren --- #### ay aggregate # `ay aggregate` (Alias: `agg`) MongoDB-Aggregation-Pipelines gegen beliebige Collections, mit 7 Subcommands für Wizard, Ausführung und Wiederverwendung. ## Subcommands | Subcommand | Zweck | |---|---| | `wizard` | Interaktiver Wizard: Collection, Stages, Output | | `exec` | Ad-hoc-Pipeline ausführen | | `run ` | Gespeicherte Pipeline ausführen | | `list` | Alle gespeicherten Pipelines | | `save ` | Pipeline speichern | | `validate` | Pipeline-Syntax prüfen | | `models` | Collections listen, die Aggregation erlauben | ## Ad-hoc-Ausführung ```bash ay aggregate exec \ --model Orders \ --pipeline '[ {"$match":{"status":"paid"}}, {"$group":{"_id":"$country","total":{"$sum":"$amount"}}}, {"$sort":{"total":-1}}, {"$limit":10} ]' ``` ## Wizard ```bash ay aggregate wizard ``` Fragt Schritt-für-Schritt: 1. Collection (aus verfügbaren Modulen) 2. Stages (Match, Group, Lookup, Project, Sort, Limit …) 3. Output-Format Am Ende zeigt der Wizard die fertige Pipeline-JSON + den Output und bietet an, beides als Saved-Pipeline zu speichern. ## Gespeicherte Pipelines ```bash ay aggregate list # Alle gespeicherten ay aggregate run revenue-by-country # Ausführen ay aggregate save revenue-by-country < pipeline.json ``` Saved-Pipelines liegen in der `Aggregations`-Collection und sind customer-scoped. ## Flags | Flag | Zweck | |---|---| | `--model ` | Ziel-Collection (PascalCase, Plural) | | `--pipeline ''` | Pipeline-Array als JSON | | `--file pipeline.json` | Pipeline aus Datei | | `--explain` | Pipeline-Execution-Plan statt Ergebnis | | `--allowDisk` | `allowDiskUse: true` für große Pipelines | | `--format` | Output-Format | ## Performance-Tipp - `--explain` vor großen Pipelines — zeigt, welche Stages Indizes nutzen können. - `$match` möglichst früh, um Volumen zu reduzieren. - `$project` vor `$lookup`, um Inputs schlank zu halten. ## Siehe auch - [list](wiki:cli/crud-core/list) — einfache Queries - [export](wiki:cli/queries/export) — Aggregat-Output exportieren --- #### ay export # `ay export` (Alias: `exp`) Daten-Export mit Pagination, Format-Wahl und Filter-Sprache. Subcommands für Run, List, Get und Configs. ## Subcommands ### `ay export run ` Exportiert die Inhalte einer Collection in einem Rutsch (Auto-Pagination). | Flag | Default | Zweck | |---|---|---| | `--format ` | `csv` | `json` / `csv` / `yaml` | | `--fields ` | alle | Projection (kommagetrennt) | | `--filter ` | — | Filter wie bei [search](wiki:cli/queries/search) | | `--sort ` | `-createdAt` | Sortierung | | `-l, --limit ` | 0 (= alles) | Limit (0 = alle Pages) | ```bash ay export run contacts --format csv --fields "firstName,lastName,email" ay export run products --format json --filter "status=active" ay export run invoices --format csv --filter "createdAt>2026-01-01" --save ``` ### `ay export list` Listet bestehende Export-Jobs. ```bash ay export list -l 25 ``` ### `ay export get ` Detail + Download-URL eines Exports. ```bash ay export get 64a1b2c3 ``` ### `ay export configs` Listet konfigurierte Export-Definitionen (z.B. wiederkehrende Exports an externe Targets). ```bash ay export configs ``` ### `ay export logs` Audit-Log aller Export-Runs. ```bash ay export logs -l 25 ``` ## Hinweis Bei `--limit 0` (Default) iteriert die CLI mit `limit=500` durch alle Pages und mergt die Payloads — geeignet für Collections bis ~50k Einträge. Für größere → [db pull](wiki:cli/devops/db) oder [aggregate](wiki:cli/queries/aggregate) mit `$out`. ## Siehe auch - [search](wiki:cli/queries/search) — Filter-Sprache - [aggregate](wiki:cli/queries/aggregate) — Pipelines - [db](wiki:cli/devops/db) — Cross-DB-Sync --- ### Streaming & Events # Streaming & Events 2 Commands für Live-Updates einer Collection und Platform-Event-Subscription. ## Commands | Command | Alias | Zweck | |---|---|---| | [stream](wiki:cli/streaming/stream) | `listen` | Live-Änderungen einer Collection (Change-Stream) | | [events](wiki:cli/streaming/events) | `sub` | Platform-Event-Bus-Subscription | ## Beispiel: Live-Consumer-Änderungen ```bash ay stream consumers # Terminal zeigt jede Insert/Update/Delete in Echtzeit ``` Flags: - `--filter ''` — nur Änderungen, die einem MongoDB-Filter matchen - `--ops insert,update` — nur bestimmte Operationen ## Beispiel: Platform-Events ```bash ay events --topic orders.paid ay events --topic '*.failed' --since 1h ``` Topics sind in der `Events`-Collection definiert (`events` Module), Pattern-Match mit `*` erlaubt. ## Siehe auch - [jobs](wiki:cli/misc/jobs) — Queue-Monitoring - [monitor](wiki:cli/devops/monitor) — Log-Streaming --- #### ay events # `ay events` (Alias: `sub`) Subscribed via WebSocket auf den aYOUne Customer-Event-Bus und filtert die Events auf der Client-Seite. Output formatiert als JSON, YAML oder Tabelle. ## Syntax ``` ay events [flags] ``` ## Flags | Flag | Default | Zweck | |---|---|---| | `-f, --format ` | `json` | `json` / `yaml` / `table` | | `-c, --category ` | `*` | Event-Category (z.B. `sales`, `crm`) | | `-a, --action ` | `*` | Action (z.B. `create`, `update`, `delete`) | | `-l, --label