CLI-Befehle für Jobs und Cloud

Überblick

Diese Seite beschreibt den Job-Transport, native DDS-Cloud-Sitzungen und Workspace-Operationen, den expliziten Legacy-HTTP-Dienstadapter sowie die 25 Aktionen des Kundenmanifests. Native Evolve-Operationen besitzen separate Anfrageverträge.

Lesen Sie zuerst die CLI-Befehlsoberfläche für die Routing-Regel, die beiden Gruppen von Exit-Codes und die Belegformate. Zu den lokal geparsten Engine-Namensräumen siehe CLI-Engine-Befehle. Aktuelle Release-Einschränkungen finden Sie in der CLI-Befehlsreferenz; wie das Manifest zu lesen ist, erläutert der Aktions- und Funktionsvertrag.

Der Namensraum job

job umfasst die Offline-Vorprüfung des Clients sowie den Job-Transport über einen Job Service. Er wird vom lokalen Parser behandelt, sodass -h funktioniert und Wertebereiche geprüft werden, bevor irgendein Dienst kontaktiert wird.

Sechs seiner acht Unterbefehle akzeptieren --runner <local|cloud|private> mit dem Standardwert cloud. Dieses Flag bestimmt, welcher Job Service angesprochen wird. Es ist nicht das Engine-Runner-Flag von rtl compile und verwandten Befehlen. job readiness und job validate haben überhaupt kein --runner und greifen nie auf ein Netzwerk zu.

<JOB_ID> und --artifact-id dürfen mit einem Bindestrich beginnen, ohne einen ---Trenner zu benötigen; der Parser akzeptiert bei diesen Argumenten Werte mit führendem Bindestrich.

Die beiden bereichsgeprüften Optionen von job wait werden vom Parser durchgesetzt, nicht vom Dienst:

$ alti job wait --poll-interval-ms 99 job-123
error: invalid value '99' for '--poll-interval-ms <POLL_INTERVAL_MS>': 99 is not in 100..=60000

Dies führt zum Abbruch mit 2.

job readiness

job readiness antwortet ohne Zugangsdaten oder Netzwerkzugriff. In diesem Release ist es eine feste Projektion ohne Pfadangaben: Jede Komponente meldet configured: false und ready: false, und das blockers-Array ist vollständig.

{
  "schema": "altifigence.engine-product-host-readiness.v1",
  "product_id": "altifigence-cli",
  "authority": { "configured": false, "ready": false },
  "admission": { "configured": false, "ready": false },
  "dispatcher": { "configured": false, "ready": false },
  "executor": { "configured": false, "ready": false },
  "artifact_readback": { "configured": false, "ready": false },
  "ready": false,
  "blockers": [
    "authority_unavailable",
    "admission_unavailable",
    "dispatcher_unavailable",
    "executor_unavailable",
    "artifact_readback_unavailable"
  ]
}

Es beendet sich mit 0. Ein 0 bedeutet hier, dass die Bereitschaftsfrage beantwortet wurde, nicht dass etwas bereit ist.

job validate

job validate ist die Offline-Vorprüfung, die in Erster Erfolg mit der CLI Schritt für Schritt beschrieben wird. Sie liest ein EngineJobV1-Dokument aus --job (oder aus stdin, wenn --job den Wert - hat oder fehlt), prüft es gegen die exakte Client-Hülle für Cloud CPU RTL und hasht eine lokale Quelldatei. Sie löst keine Zugangsdaten auf, erstellt keinen Client und kontaktiert nichts.

Das Belegschema ist altifigence.cli.engine-job-preflight.v1. Bei Erfolg hat status den Wert client_preflight_valid, submitted den Wert false, server_authority_verified den Wert false, job_schema den Wert altifigence.engine.job.v1, execution_placement den Wert cloud, der operation-Block lautet rtl-engine / analyze / rtl-analysis-request.v1, und der source-Block enthält workspace_uri, sha256 und size_bytes.

Das Job-Dokument wird mit einer festen Grenze von 8388608 Bytes gelesen. Oberhalb dieser Grenze schlägt der Befehl mit folgender Meldung fehl: EngineJobV1 JSON exceeds the CLI limit.

Cloud-Einreichungen erfordern eine explizite Zustimmung zum Quell-Upload

Bei --runner cloud benötigen sowohl job submit und analyze run alle drei Optionen für den Quell-Upload gemeinsam. In diesem Release kann ein Cloud-CPU-RTL-Job nicht ohne sie eingereicht werden:

$ alti job submit --job job.json
error: Cloud Engine Job source upload is disabled; pass --allow-source-upload explicitly.

Dies führt zum Abbruch mit 1. Bei --allow-source-upload ohne --workspace-root lautet die Meldung --workspace-root is required with --allow-source-upload.; entsprechend gilt dies für --source.

--workspace-root muss absolut sein. --source ist ein portabler relativer Pfad unterhalb von <workspace-root>/inputs.

Artefaktdownloads aus der Cloud erfordern eine eigene Zustimmung

Bei job result mit --runner cloud bilden die drei Artefaktoptionen eine Gruppe. Sobald eine von ihnen angegeben wird, wechselt der Befehl in den Downloadmodus und benötigt dann alle drei:

• Ohne --allow-artifact-download: Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• Ohne --artifact-id: --artifact-id is required with --allow-artifact-download.

• Ohne --output-dir: --output-dir is required with --allow-artifact-download.

--output-dir muss ein absolutes Verzeichnis sein. --artifact-id stammt aus der Ausgabeliste eines endgültigen EngineResultV1.

Ablehnungen mit Runner-Bezug

Drei Optionsgruppen sind auf einen Runner beschränkt und werden außerhalb davon abgelehnt. Alle diese Entscheidungen erfolgen, bevor ein Prozess startet oder eine Anfrage gestellt wird:

Der ältere local/private-Pfad nennt den ausgemusterten Adapter alti-engine-job, der nicht im Release-Inventar der 24 Runner enthalten ist. Akzeptierte Runner-Syntax und Endpunktvariablen belegen keinen ausgelieferten lokalen/privaten Job Service. Verwenden Sie den integrierten Cloud-Pfad nur dort, wo Dienst und Konto freigeschaltet sind, oder einen dokumentierten direkten lokalen Engine-Befehl.

Maschinenlesbare Job-Fehler

job-Unterbefehle und analyze run geben bei einem Aufruf mit --json im Fehlerfall eine strukturierte Fehlerhülle statt einer einfachen Meldung aus:

{
  "schema": "altifigence.cli.error.v1",
  "error": {
    "code": "ENGINE_JOB_JSON_INVALID",
    "message": "The engine job JSON is invalid.",
    "retryable": false
  }
}

Die vollständige Liste der Codes lautet:

retryable ist in diesem Release bei jedem dieser Fehler false. Diese Hülle wird für den Namensraum job und analyze run ausgegeben. Andere Befehlsfamilien verwenden eigene Fehler-/Belegverträge; siehe Befehlsreferenz.

analyze run und evolve run

analyze run und die expliziten nativen Evolve-Unterbefehle erreichen den lokalen Parser. Die einwortigen Kundenaktionen analyze und evolve sind separate Verträge.

analyze run akzeptiert dieselben Optionen wie job submit und folgt derselben Regel für Quell-Uploads in die Cloud. Es unterscheidet sich in einem Punkt: Es akzeptiert --runner, lehnt aber jeden Wert außer cloud ab.

$ alti analyze run --runner local --job job.json
error: Local and Private job service adapters are not available; use --runner cloud.

Dies führt zum Abbruch mit 1.

evolve run hat kein --runner, kein --project und keine Argumentdurchleitung. Es liest ein Anfragedokument – --request - liest stdin – und leitet an die mitgelieferte Engine alti-evolve weiter, deren Exit-Status durchgereicht wird:

$ echo '' | alti evolve run --request -
alti-evolve: invalid request JSON: EOF while parsing a value at line 1 column 0

Dieser Wert 2 ist der durchgereichte eigene Exit-Status von alti-evolve, kein CLI-Argumentfehler. Bei einer Installation, in der die Engine nicht aufgelöst werden kann, endet derselbe Befehl mit 127 und einem Beleg, dessen status den Wert unavailable hat.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa und evolve artifact werden ebenfalls geroutet. Beispielsweise analysiert evolve analyze SAVED_RTL --top TOP [--project ABS] gespeicherte Quellen. Zulassung, Bereitschaft und Vorprüfung für gemessene PPA erzeugen keine gemessenen PPA.

Die öffentliche GPU-Aktivitätsoperation ist compute rtl-evolve --request FILE_OR_DASH. Sie hat eine separate native Generierungshülle und eine explizite CPU-Referenz-/CUDA-Richtlinie. Siehe Engine-Befehle, statt eine evolve run-Anfrage daran weiterzuleiten.

Digital Design Studio Cloud

Verwenden Sie ide cloud login, anschließend ide cloud whoami, um die Identität der nativen Sitzung zu prüfen. refresh und logout verwalten diese Sitzung; --session-dir wählt eine private Alternative zum Standard. Siehe CLI-Authentifizierung.

ide cloud contract --request FILE_OR_DASH validiert eine typisierte Projekt-/Mitglied-/Quell-/Workspace-Anfrage offline. ide cloud run --request FILE_OR_DASH sendet diese Anfrage mit der gespeicherten Sitzung über die native API. Anfragen mit Quellinhalten benötigen --allow-source-upload. Vertragsvalidierung gewährt niemals Organisationszugriff und ersetzt nicht die aktuellen Berechtigungen des Dienstes.

alti ide cloud search --org "$ORG_ID" --project "$PROJECT_ID" \
  --query 'module' --limit 80
alti ide cloud terminal --org "$ORG_ID" --project "$PROJECT_ID" \
  --name cli --max-seconds 60

Verwenden Sie tatsächliche autorisierte Organisations-/Projekt-UUIDs. Die Suche akzeptiert --match-case, --whole-word, einen konservativen Regex mit fester Breite --regex, --limit 1..500 und --timeout-seconds 1..120. Sie nutzt vorhandene, auf den jeweiligen Bereich begrenzte files/read-Routen und gespeicherten Inhalt mit Budgets von 500 Dateien, 4 MiB/Datei, insgesamt 16 MiB und 1 MiB Ausgabe. Änderungen an Manifest, Header oder Generation machen einen gemischten Snapshot ungültig. Der zurückgegebene contentHash hasht den exakt gelesenen UTF-8-Text und muss beim aktuellen Cloud-Eigentümer fileVersion entsprechen. Bewahren Sie fileVersion und workspaceRevision als separate CAS-Felder auf.

Terminal-Anbindung bewahrt den WebSocket-Transport und die aktuelle Autorisierung. Sie streamt stdout-Bytes; Statusmeldungen gehen auch mit globalem --json an stderr. Verwenden Sie --cursor zum Fortsetzen sowie --cols 2..500, --rows 1..200 und --max-seconds 1..300, um die Anbindung zu begrenzen. Das Trennen ist keine Aufforderung, das dauerhaft bestehende PTY zu beenden. Dies ist Ausführung im Cloud-Projekt, keine lokale CLI-Shell.

Legacy-DDS-Workspace-Dienst

ide service spricht einen explizit konfigurierten Legacy-HTTP-Workspace-Eigentümer an. Setzen Sie --endpoint oder ALTI_STUDIO_ENDPOINT und dessen vorhandenes ALTI_STUDIO_SERVICE_SECRET in der privaten Umgebung des Aufrufers. Weder eine native Cloud-Sitzung noch ein Browser-Cookie oder beliebige URL-/Body-Weiterleitung werden ersatzweise verwendet. Dies beschreibt den Legacy-Dienstadapter und behauptet weder, dass die aktuelle native Desktop-Oberfläche diese Endpunkte nutzt, noch dass ein öffentlicher Produktionsdienst freigeschaltet ist.

Die Suche akzeptiert --match-case, --whole-word, einen konservativen Regex mit fester Breite --regex und --limit 1..1000 (Standardwert 80). Die Regex-Zulassung akzeptiert bewusst nur eine Teilmenge der JavaScript-Syntax des Eigentümers; Gruppen, Alternativen und Quantifizierer werden abgelehnt. Die eigentliche Suche im Backend bleibt Aufgabe des Dienstes.

Ersetzung akzeptiert ein geschlossenes JSON-Objekt mit den erforderlichen Feldern query, replacement, paths: [one portable path] und expectedHashes: {same path: 64 hex digits}. Das optionale options enthält ausschließlich die booleschen Felder matchCase, regex und wholeWord. Das optionale match enthält dasselbe path sowie die von 1 an gezählten Ganzzahlen line/column zwischen 1 und 4194305. Lassen Sie match weg, um innerhalb der ausgewählten Datei zu ersetzen, nicht im gesamten Workspace. Beziehen Sie den Hash aus dem aktuellen Ergebnis desselben Dienstes.

Anfragen umfassen höchstens 64 KiB einschließlich JSON-Codierung und Ersetzungstext. Unbekannte Felder, nicht übereinstimmende Hash-Schlüssel/Pfade, ungültige Indizes, Traversal, Links außerhalb der Servergrenze und geschützte Metadaten bzw. von der Suche ausgeschlossene Pfade werden nicht unterstützt. Die CLI lehnt ungültige Strukturen und geschützte Pfade vor HTTP ab; Dateisystemeigentum und Linkprüfungen bleiben beim Dienst. Sie führt niemals lokale Workspace-Ersetzungen durch.

Antworten sind auf 8 MiB begrenzt. --timeout-seconds 1..3600 setzt die vollständige HTTP-Frist (Standardwert 30); Weiterleitungen und automatische Wiederholungen sind deaktiviert. Der altifigence.dds.service-receipt.v1 bewahrt HTTP-Status und Body, einschließlich einer leeren erfolgreichen DELETE-Antwort. Ein 409 bleibt ein Konflikt. Backend-CAS und Atomarität sind keine backendübergreifende Garantie; lokale/Cloud-Inhalts-Hashes dürfen ohne den entsprechenden Vertrag nicht anstelle des erwarteten Hashs dieses Dienstes verwendet werden.

Das Aktionsmanifest

Alles, was nicht vom lokalen Parser behandelt wird, geht an den Manifest-Dispatcher, der Ihren Befehlspfad gegen das eingebettete customer-tools.v1.json abgleicht. alti commands gibt das gesamte Manifest als ein JSON-Array mit fünfundzwanzig Einträgen aus und beendet sich mit 0 ohne Zugangsdaten.

Zweiundzwanzig Einträge sind als executes: true gekennzeichnet. Drei – analyze, evolve und verify – sind executes: false und geben vor der Weiterleitung einen [plan-only]-Hinweis aus. Dieselben drei sind die einzigen, die Quellbytes enthalten; sie sind durch --allow-source-upload abgesichert.

Vierzehn der fünfundzwanzig enthalten zusätzlich das Profil remote_core; die übrigen haben nur local_extended. Was dieses Profil für die Verfügbarkeit bedeutet, beschreibt der Aktions- und Funktionsvertrag.

Jede nachfolgende Aktion liest ALTI_TOKEN und ALTI_ORG_ID aus der Prozessumgebung, bevor sie einen Client erstellt, und scheitert mit Exit-Code 1, wenn einer der Werte fehlt:

$ alti credits
Config error: ALTI_TOKEN is not set (org API key or access token).

Gemeinsame Optionen für Listenaktionen

Mehrere Aktionen verwenden dieselbe Seiteneinteilung: --limit <INTEGER> im Bereich 1..=100 und --cursor <STRING>. Beide werden lokal validiert, bevor eine Anfrage gestellt wird:

$ alti project ls --limit 101
Invalid value for --limit: outside allowed range.

Dies führt zum Abbruch mit 2, ebenso wie ein unbekanntes Flag (Unknown option(s): --limti), eine fehlende erforderliche Option (Missing required option(s): --projectId) oder ein Wert außerhalb der Aufzählung (Invalid value for --visibility: expected one of public, private.).

Workspaces und Projekte

Dialogbasierte RTL

chat models wird vor chat abgeglichen, da der Dispatcher den längsten passenden Befehlspfad bevorzugt. alti chat unterliegt serverseitig einer Guthabenprüfung und wird im Audit-Protokoll erfasst.

Schätzungen und Aktionen zur reinen Planung

--rtl und --testbench sind Inline-Quellstrings mit einer festen Grenze von jeweils 1048576 Bytes, die lokal geprüft wird:

$ alti analyze --target kv260-fpga --rtl "$(cat huge.sv)" --allow-source-upload
Invalid value for --rtl: exceeds size limit.

Dies führt zum Abbruch mit 2. Ohne --allow-source-upload beendet sich jede dieser drei Aktionen mit 4, bevor ein Client erstellt wird:

Source upload is disabled by default. Re-run with --allow-source-upload only
after reviewing the destination and input.

Diese drei sind executes: false; auch bei Zustimmung geben sie daher einen [plan-only]-Hinweis an stderr aus, und der Server liefert einen strukturierten Dispatch-Plan statt eines Laufs zurück.

Artefakte, Nachweise, Runner und Abrechnung

MCP-Register

Diese Befehle lesen das vom Server angegebene MCP-Werkzeugregister und die organisationsbezogene Freigabeliste. Sie haben nichts mit alti mcp serve zu tun; dieser Befehl wird vor beiden Dispatchern abgefangen und startet den lokalen stdio-Server. Siehe MCP.

Eine Manifestaktion ist nicht erreichbar

Das Manifest definiert eine einwortige trace-Aktion für Trace-Zusammenfassungen. Sie kann nicht aufgerufen werden, weil trace vom lokalen Parser als Engine-Namensraum beansprucht wird. alti trace erreicht den lokalen Parser, findet keinen Unterbefehl und beendet sich mit 2; alti trace --limit 5 erreicht ihn ebenfalls und beendet sich mit 2 bei einem unbekannten Argument.

Die Aktion ist weiterhin in der Ausgabe von alti commands enthalten; deshalb beträgt die Zahl dort fünfundzwanzig, während vierundzwanzig Befehle erreichbar sind. Filtern Sie diese Aktion heraus, wenn Sie das Manifest programmgesteuert aufzählen.

Den Cloud-Workflow wählen

Verwenden Sie keine ID, keinen Hash und keinen Beleg aus einem anderen Workflow, sofern dessen Vertrag dies nicht ausdrücklich akzeptiert. Ein erneut verbundenes Terminal bleibt die vorhandene Remote-Sitzung; eine verlorene Einreichungsantwort kann weiterhin zu einem bereits vorhandenen Job gehören. Prüfen Sie den Zustand, bevor Sie ein Duplikat erstellen.