Zero CLI: check, run, build, test, fix, explain 명령어 정리

CLI가 제공하는 것

zero 바이너리는 개발 툴체인 전체를 담고 있습니다. 별도의 패키지 매니저, 포매터, 린터, 테스트 러너가 없어요. 전부 zero의 서브커맨드로 들어 있죠. 표면적이 작고 예측 가능해진다는 점이 핵심입니다.

가장 자주 만나게 될 명령어 모음입니다.

명령어	하는 일
zero check	실행 파일을 만들지 않고 소스를 타입 검사.
zero run	컴파일과 실행을 한 단계로.
zero build	네이티브 실행 파일로 컴파일.
zero test	패키지의 테스트 타겟 실행.
zero fix	구조화된 수정 계획 적용 또는 미리보기.
zero explain	진단 코드에 대한 산문 설명 조회.
zero new	새 패키지 스캐폴딩.
zero --version	툴체인 버전 출력.

각 명령은 모두 사람용 텍스트 대신 기계가 읽을 수 있는 출력을 받기 위해 --json을 지원합니다.

zero check

가장 자주 쓰는 명령입니다. zero check는 컴파일러의 정적 검사 — 파싱, 타입 검사, 능력과 효과 추론, 누락된 import 감지 — 를 돌리고 코드 생성 전에 멈춥니다. 빠르다는 점이 중요합니다. 에이전트와 에디터가 이 명령을 끊임없이 호출하기 때문이죠.

zero check hello.0

출력이 없고 종료 코드가 0이면 파일이 잘 형성되어 있다는 뜻입니다. 에러는 기본적으로 사람이 읽기 좋은 텍스트로 출력됩니다. --json을 붙이면 에이전트가 소비하는 구조화된 형태가 됩니다.

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

진단의 형식은 JSON 진단 문서에서 자세히 다룹니다. 안정적인 code 필드에 주목하세요. NAM003은 컴파일러 버전과 상관없이 늘 "unknown identifier"를 의미합니다.

check는 단일 파일 대신 패키지 디렉터리를 가리킬 수도 있습니다.

zero check ./my-package

zero.json을 읽고 소스 트리를 순회한 뒤 모든 타겟에 걸쳐 문제를 보고합니다.

zero run

run은 컴파일과 실행을 한 단계로 묶습니다. 작은 프로그램을 반복적으로 다듬고 있고 디스크에 바이너리를 남기는 게 중요하지 않을 때 좋습니다.

zero run hello.0

zero build로 빌드한 뒤 결과 바이너리를 호출하는 것과 같지만, 결과물은 버려집니다. 프로그램의 표준 출력은 터미널의 표준 출력으로 그대로 흘러갑니다. 프로그램의 world.out.write 호출이 화면에 나타나는 거죠.

프로그램에 인자가 필요하다면 -- 다음에 전달하세요.

zero run greet.0 -- Alice

런타임은 I/O를 노출하는 같은 World 능력을 통해 프로그램에 이 인자들에 대한 접근을 제공합니다.

zero build

결과물이 필요하다면 build를 씁니다.

zero build hello.0

컴파일러는 소스 파일 옆에(패키지 안이라면 패키지의 빌드 디렉터리에) 네이티브 실행 파일을 만들어 줍니다. 어느 프로그램이든 같은 방식으로 실행할 수 있어요. Zero 바이너리는 자체 완비형이라 별도의 런타임이 필요 없습니다.

Zero 바이너리는 크기가 작습니다. 프로젝트의 설계 목표는 사소한 프로그램에 대해 10KB 미만의 실행 파일이고, LLVM 툴체인을 거치지 않고 콤팩트한 코드 경로를 직접 내보내는 방식으로 이를 달성합니다.

zero test

패키지의 테스트 타겟을 실행합니다.

zero test

테스트는 src/ 아래에 소스와 함께 위치하고, 패키지의 zero.json에 테스트 타겟으로 선언됩니다. 러너가 이를 찾아 각각 실행한 뒤 통과/실패를 출력합니다. --json을 붙이면 에이전트와 CI 도구를 위해 테스트마다 이름, 상태, 시간, 캡처한 진단이 구조화된 형태로 나옵니다.

Zero 패키지 문서에서 zero.json에 테스트 타겟을 선언하는 법을 다룹니다.

zero fix

fix는 check --json이 만들어내는 수정 메타데이터를 소비합니다. 두 가지 모드가 있습니다.

zero fix --plan --json   # 구조화된 계획만 보여주고 적용은 하지 않음
zero fix                 # 계획을 그 자리에 적용

계획은 대략 이렇게 생겼습니다(형식은 예시 수준입니다).

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

아이디어는 이렇습니다. 에이전트가 계획을 가져와 신뢰할지 결정한 뒤, 곧바로 적용하거나 더 상위 추론 단계로 넘깁니다. 계획은 데이터입니다. 에이전트가 산문을 해석해서 행동할 필요가 없어요.

zero explain

explain은 진단 시스템의 산문 측면입니다.

zero explain NAM003

에러 코드에 대한 사람이 읽을 수 있는 설명을 출력합니다. 무엇을 뜻하는지, 컴파일러가 왜 이 진단을 내는지, 흔한 수정은 무엇인지 같은 내용이에요. 다음과 같은 상황에서 유용합니다.

• 사람이 디버깅 중인데 인라인 메시지보다 긴 답이 필요할 때.
• 에이전트가 학습 데이터에 없던 진단 코드를 만나 더 많은 맥락이 필요할 때.

코드 자체는 컴파일러 버전 사이에서도 안정적이라, 캐싱해 둔 설명도 그대로 유효합니다.

zero new

새 패키지를 스캐폴딩합니다.

zero new cli hello

이 명령은 zero.json 매니페스트와 시작용 src/main.0을 담은 hello/ 디렉터리를 만듭니다. 첫 번째 인자(cli)는 템플릿을 고릅니다. 여기서는 실행 가능한 커맨드라인 앱이죠. Zero 패키지 문서에서 레이아웃을 자세히 설명합니다.

--json 습관

거의 모든 명령이 --json을 지원합니다. Zero를 둘러싸고 도구, 에이전트 하니스, CI 파이프라인을 구축한다면 기본을 JSON 형태로 두세요. 이유는:

• 안정적입니다. 스키마에 버전이 매겨져 있고, 팀이 이를 계약으로 다룹니다.
• 완전합니다. 사람용 출력에는 없는 필드(정확한 범위, 수정 계획 ID, 의존성 그래프 데이터)까지 받을 수 있습니다.
• 파싱하기 쉽습니다. 영문 산문에서 줄 번호를 추출하려고 정규식을 돌릴 필요가 없어요.

사람이 보는 용도라면 --json은 빼는 편이 낫습니다. 터미널에서는 정돈된 텍스트가 더 잘 읽힙니다.

그 외 유용한 명령어

자주 쓰지는 않더라도 알아 두면 좋은 명령어 몇 가지입니다.

• zero graph --json — 패키지의 의존성 그래프를 구조화된 데이터로 내보냅니다. 무엇이 무엇에 의존하는지 파악하거나, 호출 지점을 만지기 전에 추론하려는 에이전트에 유용합니다.
• zero size --json — 컴파일된 결과물의 디스크 크기를 타겟별로 보고합니다. 바이너리 크기가 중요할 때 도움이 됩니다(Zero의 설계 목표이기도 하죠).
• zero --version — 툴체인 버전을 출력합니다. 팀 작업이라면 어딘가에 고정해 두세요. Zero는 1.0 이전이라 깨지는 변경이 들어옵니다.

다음 글: Zero 패키지

단일 .0 파일은 hello-world에는 충분합니다. 실제 프로젝트는 zero.json 매니페스트와 src/ 디렉터리가 있는 패키지를 씁니다. Zero 패키지에서 스캐폴딩하는 방법과 모든 필드의 의미를 설명합니다.