CLI 작업 및 Cloud 명령어

개요

이 페이지는 작업 통신, 네이티브 DDS Cloud 세션·워크스페이스 작업, 명시적인 레거시 HTTP 서비스 어댑터, 고객 manifest 액션 25개를 다룹니다. 네이티브 Evolve 작업은 별도 요청 계약을 사용합니다.

라우팅 규칙과 두 종류의 종료 상태, 리시트 엔벌로프는 CLI 명령 인터페이스에서 먼저 확인하세요. 로컬 parser가 처리하는 엔진 네임스페이스는 CLI 엔진 명령, 현재 제한사항은 CLI 명령 레퍼런스, 매니페스트 읽는 방법은 액션과 capability 계약에 정리되어 있습니다.

job 네임스페이스

job는 오프라인 클라이언트 사전 검사과 Job Service에 대한 작업 전송을 다룹니다. 로컬 파서에서 처리되므로 -h가 작동하고 모든 것이 연결되기 전에 값 범위를 확인합니다.

8개의 하위 명령 중 6개는 --runner <local|cloud|private>이며, 기본값은 cloud입니다. 이 플래그는**어떤 Job Service와 대화해야 하는가?**을 선택합니다. rtl compile 및 친구에 대한 엔진 러너 플래그가 아닙니다. job readiness 및 job validate에는 --runner가 전혀 없으며 네트워크를 터치하지 않습니다.

<JOB_ID> 및 --artifact-id는 -- 구분자를 사용하지 않고 하이픈으로 시작할 수 있습니다.

job wait에 대한 두 가지 범위 검사 옵션은 서비스가 아닌 파서에 의해 시행됩니다.

$ 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

2를 종료합니다.

작업 준비

job readiness는 자격 증명이나 네트워크 없이 동작합니다. 현재 버전에서는 경로를 사용하지 않는 고정된 상태를 반환합니다. 모든 구성 요소의 값은 configured: false, ready: false이며, 사용할 수 없는 이유는 blockers 배열에 표시됩니다.

{
  "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"
  ]
}

0를 종료합니다. 여기서 0는 준비가 완료되었음을 의미하며 모든 준비가 완료되었음을 의미하지는 않습니다.

작업 유효성

job validate는 CLI 첫 실행에서 단계적으로 문서화된 오프라인 사전 검사 문서입니다. --job에서 EngineJobV1 문서를 읽습니다 (또는 --job가 -이거나 생략 된 경우 stdin), 정확한 클라우드 CPU RTL 클라이언트 엔벌로프에 대해 검사하고 클라이언트 엔벌로프를 생성하지 않고 로컬 소스를 해결합니다.

영수증 스키마는 altifigence.cli.engine-job-preflight.v1입니다. 성공하면 status는 client_preflight_valid, submitted는 false, server_authority_verified는 false, job_schema는 altifigence.engine.job.v1, execution_placement는 cloud입니다. operation 블록은 rtl-engine / analyze / rtl-analysis-request.v1이며, source 블록에는 workspace_uri, sha256, size_bytes가 포함됩니다.

작업 문서는 8388608 바이트의 하드 바운드로 읽습니다. 위의 명령은 EngineJobV1 JSON exceeds the CLI limit.로 실패합니다.

클라우드 제출 시 분명한 소스 옵트인 필요

--runner cloud를 사용하면 job submit와 analyze run 모두 세 가지 소스 업로드 옵션이 함께 필요합니다. 이 릴리스에서 클라우드 CPU RTL 작업을 제출하는 방법은 없습니다.

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

1를 종료합니다. --allow-source-upload를 사용하지만 --workspace-root를 사용하지 않으면 메시지가 --workspace-root is required with --allow-source-upload.이며 --source도 마찬가지입니다.

--workspace-root는 절대값이어야 합니다. --source는 <workspace-root>/inputs 아래의 휴대용 상대 경로입니다.

클라우드 아티팩트 다운로드에는 자체 옵트인이 필요합니다.

--runner cloud를 사용하는 job result에서 세 가지 아티팩트 옵션은 그룹입니다. 이들 중 하나를 전달하면 명령을 다운로드 모드로 전환 한 다음 세 가지 모두 필요합니다.

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

• --artifact-id 없이: --artifact-id is required with --allow-artifact-download.

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

--output-dir는 절대 디렉터리여야 합니다. --artifact-id는 터미널 EngineResultV1의 출력 목록에서 가져옵니다.

러너 스코프 거부

다음 세 옵션 그룹은 특정 러너에서만 사용할 수 있습니다. 프로세스를 시작하거나 요청을 보내기 전에 잘못된 조합을 검사합니다.

이전 local/private 경로는 폐기된 alti-engine-job 어댑터를 지정하며, 이는 실행기 24개의 릴리스 목록에 없습니다. runner 구문과 엔드포인트 변수를 받는다는 사실이 local/private Job Service의 제공을 입증하지는 않습니다. 서비스와 계정이 활성화된 경우에만 내장 Cloud 경로를 사용하거나, 문서화된 직접 로컬 엔진 명령을 사용하세요.

프로그램에서 처리할 수 있는 작업 오류

--json으로 실행한 job 하위 명령과 analyze run은 실패할 때 일반 문자열 대신 구조화된 error 엔벌로프를 출력합니다.

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

전체 코드 세트는 다음과 같습니다.

이 릴리스에서는 모두 retryable이 false입니다. 이 응답 형식은 job 이름 공간과 analyze run에서 출력합니다. 다른 명령군은 자체 오류·영수증 계약을 사용합니다. 명령 레퍼런스를 참조하세요.

analyze run 및 evolve run

analyze run과 명시적인 네이티브 Evolve 하위 명령은 로컬 파서로 연결됩니다. 한 단어인 고객 액션 analyze, evolve는 별도 계약입니다.

analyze run는 job submit와 동일한 옵션을 설정하고 동일한 클라우드 소스 업로드 규칙을 따릅니다. --runner를 수락하지만 cloud를 제외한 모든 것을 거부합니다.

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

1를 종료합니다.

evolve run에는 --runner, --project 및 passthrough가 없습니다. 하나의 요청 문서 --request -가 stdin을 읽고 패키지 alti-evolve 엔진으로 전달합니다.

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

이 2는 CLI 인수 오류가 아니라 alti-evolve 자체의 종료 상태가 전달된 값입니다. 엔진을 찾을 수 없는 설치에서는 같은 명령이 종료 코드 127과 status가 unavailable인 영수증을 반환합니다.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa, evolve artifact도 연결됩니다. 예를 들어 evolve analyze SAVED_RTL --top TOP [--project ABS]는 저장된 소스를 분석합니다. measured-PPA의 허용 검사·준비 상태·사전 검사는 측정된 PPA를 생성하지 않습니다.

공개 GPU 활동 작업은 compute rtl-evolve --request FILE_OR_DASH입니다. 별도의 네이티브 생성 요청과 명시적인 CPU-reference/CUDA 정책을 사용합니다. evolve run 요청을 전달하지 말고 엔진 명령을 참조하세요.

Digital Design Studio Cloud

ide cloud login 후 ide cloud whoami로 네이티브 세션의 식별 정보를 검증하세요. refresh와 logout은 해당 세션을 관리하고 --session-dir은 기본 경로 대신 사용할 비공개 경로를 선택합니다. CLI 인증을 참조하세요.

ide cloud contract --request FILE_OR_DASH는 타입 기반 프로젝트·구성원·소스·워크스페이스 요청을 오프라인에서 검증합니다. ide cloud run --request FILE_OR_DASH는 저장된 세션으로 네이티브 API를 통해 요청을 보냅니다. 소스가 포함된 요청에는 --allow-source-upload가 필요합니다. 계약 검증은 조직 접근 권한을 부여하거나 서비스의 현재 권한을 대체하지 않습니다.

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

실제로 권한이 부여된 조직·프로젝트 UUID를 사용하세요. 검색은 --match-case, --whole-word, 보수적인 고정 폭 --regex, --limit 1..500, --timeout-seconds 1..120을 받습니다. 기존 범위 지정 files/read 경로와 저장된 내용을 사용하며 파일 500개, 파일당 4 MiB, 총 16 MiB, 출력 1 MiB로 제한합니다. manifest·header·generation이 바뀌면 혼합 스냅샷은 무효가 됩니다. 반환된 contentHash는 정확히 읽은 UTF-8 텍스트의 해시이며 현재 Cloud 소유 서비스에서는 fileVersion과 같아야 합니다. fileVersion과 workspaceRevision은 별도의 CAS 필드로 보관하세요.

터미널 연결은 WebSocket 통신과 현재 권한을 유지합니다. stdout 바이트를 스트리밍하며 전역 --json을 사용해도 상태는 stderr로 보냅니다. 재개에는 --cursor, 연결 제한에는 --cols 2..500, --rows 1..200, --max-seconds 1..300을 사용하세요. 연결 해제는 지속되는 PTY를 종료하라는 요청이 아닙니다. 이는 로컬 CLI 셸이 아닌 Cloud 프로젝트 실행입니다.

레거시 DDS 워크스페이스 서비스

ide service는 명시적으로 설정된 레거시 HTTP 워크스페이스 소유 서비스를 대상으로 합니다. 호출자의 비공개 환경에 --endpoint 또는 ALTI_STUDIO_ENDPOINT와 기존 ALTI_STUDIO_SERVICE_SECRET을 설정하세요. 네이티브 Cloud 세션, 브라우저 쿠키, 임의 URL·본문 전달로 대체하지 않습니다. 이는 레거시 서비스 어댑터에 대한 설명이며, 현재 네이티브 데스크톱 UI가 이 엔드포인트를 사용하거나 공개 운영 서비스가 활성화됐다는 주장이 아닙니다.

검색은 --match-case, --whole-word, 보수적인 고정 폭 --regex, --limit 1..1000을 받으며 기본 제한은 80입니다. 정규식 허용 검사는 소유 서비스의 JavaScript 구문 중 일부만 받도록 의도적으로 제한합니다. 그룹, 선택, 수량자는 거부합니다. 실제 일치 처리는 서비스가 담당합니다.

바꾸기는 필수 query, replacement, paths: [one portable path], expectedHashes: {same path: 64 hex digits}를 포함한 닫힌 JSON 객체를 받습니다. 선택적 options에는 boolean인 matchCase, regex, wholeWord만 넣을 수 있습니다. 선택적 match는 같은 path와 1~4194305의 1부터 시작하는 정수 line·column을 포함합니다. match를 생략하면 전체 워크스페이스가 아니라 선택한 파일 안에서 바꿉니다. 해시는 같은 서비스의 현재 결과에서 얻으세요.

요청은 JSON 인코딩과 바꿀 텍스트를 포함해 최대 64 KiB입니다. 알 수 없는 필드, 불일치하는 해시 키·경로, 잘못된 위치, 경로 순회, 서버 경계 밖 링크, 보호된 메타데이터·검색 제외 경로는 지원하지 않습니다. CLI는 HTTP 요청 전에 잘못된 형식과 보호 경로를 거부합니다. 파일 시스템 소유권과 링크 검사는 서비스가 담당합니다. 로컬 워크스페이스 바꾸기는 수행하지 않습니다.

응답은 8 MiB로 제한됩니다. --timeout-seconds 1..3600은 전체 HTTP 시간 제한을 설정하며 기본값은 30입니다. 리다이렉트와 자동 재시도는 비활성입니다. altifigence.dds.service-receipt.v1은 성공한 DELETE의 빈 응답을 포함해 HTTP 상태와 본문을 유지합니다. 409는 충돌로 남습니다. 백엔드의 CAS·원자성은 백엔드 간 보장이 아니며, 계약상 근거 없이 로컬·Cloud 내용 해시를 해당 서비스의 예상 해시로 대체하면 안 됩니다.

액션 매니페스트

Local parser가 처리하지 않는 명령은 manifest dispatcher로 넘어가 내장 customer-tools.v1.json과 경로를 대조합니다. alti commands는 자격 증명 없이 25개 항목의 전체 매니페스트를 JSON 배열 하나로 출력하고 종료 상태 0을 반환합니다.

22개의 항목은 executes: true로 표시되어 있습니다. 3개 — analyze, evolve 및 verify —는 executes: false이며 dispatch 전에 [plan-only] 노트를 인쇄합니다. 이 3개만이 소스 바이트를 운반하는 유일한 항목이며 --allow-source-upload 뒤에 게이트가 있습니다.

25명 중 14명도 remote_core 프로파일을 가지고 있습니다. 나머지는 local_extended에만 해당됩니다. 해당 프로파일이 의미하는 바는 활동 및 능력 계약에서 다룹니다.

아래의 모든 동작은 클라이언트를 구성하기 전에 프로세스 환경에서 ALTI_TOKEN 및 ALTI_ORG_ID를 읽고, 다음 중 하나가 누락된 경우 1 종료와 함께 실패합니다.

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

목록 작업에 공통적인 옵션

여러 액션이 같은 페이지네이션 옵션을 사용합니다. --limit <INTEGER>는 1..=100 범위이며 --cursor <STRING>도 받을 수 있습니다. 두 값은 요청을 보내기 전에 로컬에서 검사합니다.

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

즉, 알 수 없는 플래그 (Unknown option(s): --limti), 누락된 필수 옵션 (Missing required option(s): --projectId) 및 범위 초과 값 (Invalid value for --visibility: expected one of public, private.)과 마찬가지로 2를 종료합니다.

작업공간 및 프로젝트

대화식 RTL

디스패처는 가장 긴 명령 경로를 먼저 찾으므로 chat models가 chat보다 먼저 매칭됩니다. alti chat의 크레딧 확인과 감사 로그는 서버에서 처리합니다.

견적 및 Plan-only 작업

--rtl 및 --testbench는 각각 1048576 바이트의 하드 제한을 가진 인라인 소스 문자열이며 로컬에서 검사합니다.

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

2를 종료합니다. --allow-source-upload가 없으면 클라이언트가 구성되기 전에 4를 종료합니다.

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

이 세 가지는 executes: false이므로 옵트인 상태에서도 stderr에 [plan-only] 노트를 인쇄하고 서버는 실행이 아닌 구조화된 디스패치 계획을 반환합니다.

아티팩트, 증거, 러너 및 결제

MCP 레지스트리

이 항목들은 서버 광고 MCP 도구 레지스트리와 per-org allowlist를 읽습니다. 이 항목들은 alti mcp serve와 관련이 없으며, 디스패처 전에 인터셉트되고 로컬 stdio 서버를 시작합니다. MCP를 참조하세요.

하나의 매니페스트 동작에 연결할 수 없음

매니페스트에는 trace summary용 한 단어 trace 액션이 있지만 실행할 수 없습니다. trace를 local parser가 엔진 네임스페이스로 먼저 처리하기 때문입니다. alti trace는 하위 명령이 없어 종료 상태 2, alti trace --limit 5도 알 수 없는 인수로 종료 상태 2를 반환합니다.

이 동작은 alti commands 출력에 여전히 존재합니다. 이 때문에 도달할 수 있는 명령 수는 24이지만 25입니다. 매니페스트를 프로그래밍 방식으로 열거하면 이 값을 필터링합니다.

Cloud 작업 경로 선택

계약에서 명시적으로 허용하지 않으면 다른 경로의 ID·해시·결과를 재사용하지 마세요. 재연결한 터미널은 기존 원격 세션이며, 제출 응답을 잃은 작업도 이미 생성됐을 수 있습니다. 중복 생성 전에 상태를 확인하세요.