chorus CLI

chorus 명령(@chorus-aidlc/chorus로 게시됨)은 세 가지 일을 합니다. Chorus 서버를 실행하고, 이 컴퓨터의 코딩 에이전트를 구성하며, 셸에서 Chorus MCP 엔드포인트를 호출합니다. 전역으로 설치합니다.

npm install --global @chorus-aidlc/chorus
chorus --version

전체 플래그 목록은 chorus --help 또는 chorus <command> --help를 실행하세요.

명령 한눈에 보기

명령	하는 일
`chorus`	Chorus 서버를 시작합니다(서브커맨드가 없을 때의 기본값). Docker로 배포를 참고하세요.
`chorus upgrade` / `chorus update`	npm 전역 CLI를 업데이트합니다. 필요하면 `--plugins`로 설정된 Chorus 플러그인도 갱신합니다.
`chorus agents`	이 컴퓨터의 에이전트를 구성합니다 — `list`(기본), `add`, `remove`, 그리고 `run`(에이전트 하나 실행).
`chorus mcp`	네이티브 MCP 클라이언트 — 도구를 `call`하거나, 자신의 UUID를 출력하거나(`whoami`), 호출 가능한 도구를 `list`합니다.
`chorus login`	에이전트로 인증하고 연결을 `~/.chorus/daemon.json`에 저장합니다.
`chorus daemon`	Chorus가 깨울 수 있도록 런타임을 온라인으로 유지합니다. Chorus 데몬 운영을 참고하세요.

CLI와 플러그인 업그레이드

Chorus 0.20.0부터 다음 명령을 사용할 수 있습니다.

chorus upgrade             # CLI만 업데이트
chorus upgrade --plugins   # CLI, 이어서 설정된 Chorus 플러그인
chorus update --plugins    # upgrade의 별칭

이 명령은 @chorus-aidlc/chorus의 npm 전역 설치에서만 동작합니다. npm의 최신 안정 버전을 확인하고, 같은 npm prefix에 있는 현재 설치를 업데이트한 뒤 설치된 버전을 검증합니다. 이미 같거나 더 높은 버전이면 재설치하거나 다운그레이드하지 않지만, --plugins 작업은 그대로 실행합니다. 소스 체크아웃, 링크 설치, 다른 패키지 관리자의 설치는 지원하지 않습니다. 이 명령이 없는 이전 CLI에서는 먼저 npm install --global @chorus-aidlc/chorus@latest로 새 버전을 설치하세요.

`--plugins`의 업데이트 범위

~/.chorus/daemon.json을 읽어 유형이 Claude Code, Codex, Kiro, Pi로 명시된 항목을 갱신합니다. 데몬 깨우기가 꺼진 항목도 포함됩니다. 갱신 대상은 각 항목의 env, PATH, 사용자 지정 설정 홈으로 정해집니다. 여러 항목이 공유하는 대상은 한 번만 업데이트하고, 서로 다른 홈은 따로 처리합니다. 현재는 기본 파일만 읽으며 CHORUS_DAEMON_CONFIG_PATH에 지정한 경로는 읽지 않습니다.

Claude Code와 Codex: 호스트의 플러그인 기능으로 Chorus 플러그인을 갱신합니다.
Kiro: 항목에 설정된 Chorus 인스턴스에서 템플릿을 가져옵니다. 새 템플릿을 받으려면 해당 서버를 먼저 업그레이드하세요. 하나의 공유 대상에 서로 다른 인스턴스 URL이 지정되어 있으면 미완료로 보고합니다.
Pi: 안정 버전 >=0.99.0 <2.0.0은 네이티브 MCP를 사용하며 대상 @chorus-aidlc/chorus-pi만 업데이트합니다. 0.84.4–0.98.x는 검증된 pi-mcp-adapter@5.0.0 고정을 유지합니다. 다른 어댑터 제약과 Chorus 고정·범위·태그도 보존하므로 설정 또는 최신 버전 갱신이 미완료일 수 있습니다. 모든 확장이나 Pi 자체를 갱신하거나 기존 어댑터를 자동 제거하지 않습니다. Pi 설정과 마이그레이션을 참고하세요.

호스트 CLI는 설치되어 있지만 Chorus 플러그인이 없으면 플러그인을 설치합니다. 등록 정보와 인증 정보는 유지하며, 호스트 CLI 자체를 설치하거나 업그레이드하지는 않습니다. 설정 파일을 변경하기 전에 <file>.chorus-upgrade.bak으로 사본을 저장하며, 이 사본은 다음 업그레이드 때 덮어씁니다.

offline 또는 알 수 없는 유형의 항목(기본 OpenCode, OpenClaw, dsh 항목 포함)과 항목의 PATH에 호스트가 없는 경우는 건너뛰고 INCOMPLETE로 보고합니다. 이런 호스트는 에이전트 플랫폼의 설정 또는 업그레이드 절차를 따르세요.

완료 상태와 적용

명령은 대화형 확인 없이 실행됩니다. 종료 코드 0은 요청한 작업 전체 완료, 1은 실패 또는 미완료 대상이 있음을 뜻합니다. 데몬 파일이 없거나 에이전트 목록이 비어 있으면 갱신할 것이 없으므로 성공으로 처리합니다. 파일을 읽을 수 없거나 형식이 잘못되면 실패합니다. CLI 업데이트가 실패하면 플러그인은 갱신하지 않습니다. 플러그인 하나가 실패해도 나머지 대상은 계속 처리하며, 완료된 업데이트는 유지됩니다(자동 롤백 없음).

npm 설치는 진행 상황을 출력하며 설치 시간 제한이 없습니다. 실패하면 표시된 npm 오류를 확인하세요. EACCES 또는 EPERM이면 사용자 소유의 Node 설치를 쓰거나 관리자에게 시스템 npm prefix 업데이트를 요청하세요. Chorus는 자동으로 권한을 올리지 않습니다. 업데이트 후에는 새 에이전트 세션을 시작하고, 편한 시점에 chorus daemon restart를 실행하세요. 실행 중인 세션과 데몬은 자동으로 재시작되지 않습니다.

에이전트 구성하기 — `chorus agents`

chorus agents add는 컴퓨터의 코딩 에이전트를 Chorus에 연결하는 하나의 명령입니다. 이미 설치되어 있는 에이전트를 감지하고, 각 에이전트의 자체 플러그인 방식으로 Chorus 플러그인을 설치하며, Chorus URL과 에이전트 키를 한 번 받아 ~/.chorus/daemon.json에 저장합니다. Claude Code, Codex, DeepSeek Harness의 경우에는 인증 정보를 그 에이전트 자신의 구성에도 쓰므로, 대화형 세션이 수동 환경 설정 없이 인증합니다(인증 정보는 어디로 가는가 참조).

chorus agents add                     # interactive: detect, pick, configure
chorus agents add --all --yes         # configure every detected agent, no prompts
chorus agents add --agents claude,codex \
  --url https://chorus.example.com --api-key cho_xxx

에이전트 추가나 인증 정보 갱신을 위해 설정을 다시 실행할 수 있습니다. Claude Code, Codex, Kiro, Pi, OpenCode, OpenClaw, Hermes, DeepSeek Harness(dsh)를 지원합니다. Pi 안정 버전 >=0.99.0 <2.0.0에는 네이티브 MCP, 0.84.4–0.98.x에는 pi-mcp-adapter@5.0.0을 선택하고 chorus-pi를 설치합니다. Pi가 없거나 미지원 또는 버전 불명이면 안내를 제공하며 무조건 MCP 설정 완료를 보고하지 않습니다. Pi를 참고하세요.

유용한 플래그(chorus agents add --help가 전부 나열합니다):

--agents <a,b> / --all — 구성할 에이전트.
--url / --api-key — 인증 정보를 비대화형으로 제공(환경 변수: CHORUS_URL / CHORUS_API_KEY).
--update-installed — 기존 설치를 갱신합니다. Pi는 pi update --extensions를 실행합니다. pi install만 반복해서는 이미 설치된 패키지가 업데이트되지 않습니다.
--dsh-profile <name> — 번들을 설치할 DeepSeek Harness 프로필.
--daemon-wake <a,b> / --daemon-wake-all — 지정한(또는 깨울 수 있는 모든) 에이전트를 데몬 깨우기 대상으로 선택합니다. 깨울 수 있는 에이전트(Claude Code, Codex, Kiro, Pi)는 기본적으로 “파킹” 상태로 추가됩니다. chorus mcp로는 접근할 수 있지만, 여기서 명시적으로 선택하거나 TTY의 에이전트별 프롬프트에서 선택하기 전까지는 데몬이 깨우지 않습니다.
--daemon-autostart — 데몬 부팅 서비스도 함께 설치·활성화(Linux systemd / macOS launchd).
--no-linger: Linux systemd lingering 설정이나 복구를 건너뛰며 기존 설정은 끄지 않습니다. 데몬 운영을 참고하세요.
-y, --yes — 확인 건너뛰기(TTY가 아니면 암묵적으로 적용되며, 이때는 --agents 또는 --all을 전달해야 합니다).

구성된 에이전트를 나열하고 제거합니다.

chorus agents                     # list configured agents (name, UUID, backend)
chorus agents remove <name|uuid>  # remove one (match by name or UUID)

chorus agents는 API 키를 절대 출력하지 않습니다. 나열된 이름이나 UUID는 chorus mcp --agent 또는 CHORUS_AGENT_PROFILE 환경 변수에 쓸 수 있는 유효한 값입니다.

Codex App Server 재시작은 --yes로 허가되지 않습니다. 인증 정보와 MCP 구성에 성공한 뒤 대화형 터미널에서만 별도의 중단 경고와 동의 질문을 표시합니다. Codex를 참고하세요.

Hermes 설정(0.22.0)

chorus agents add --agents hermes --hermes-cwd /path/to/repo는 CLI 릴리스 태그에서 chorus와 chorus-mcp를 설치하고 $HERMES_HOME/.env, 저장소, 미설정 승인 옵션을 구성합니다. --hermes-cwd <path>가 우선하며 생략하면 기존 디렉터리나 현재 Git 저장소를 사용합니다. 태그가 없으면 실패합니다.

Hermes는 Chorus daemon에서 offline으로 등록됩니다. chorus upgrade --plugins와 chorus agents run --type hermes는 지원하지 않습니다. CLI 업데이트 후 chorus agents add --agents hermes로 둘 다 다시 설치하고 hermes gateway restart를 실행합니다. 릴리스 태그 설치, 원격 MCP, 스킬, 소유자 승인은 Hermes Agent를 참조하세요.

에이전트 실행하기 — `chorus agents run`

chorus agents run은 구성된 에이전트를 Chorus 연결 정보가 이미 설정된 상태로 터미널에서 실행합니다 — 데몬 깨우기의 포그라운드 버전입니다. 자식 프로세스는 부모 셸의 환경을 바꿀 수 없으므로, 이 명령은 연결을 실행되는 에이전트 프로세스에 직접 주입합니다. 따라서 아무것도 직접 내보낼 필요가 없습니다.

chorus agents run --name work -- --model opus        # 에이전트 "work"를 실행하고 --model opus를 전달
chorus agents run                                    # 구성된 에이전트가 하나뿐이면 그것을 실행
chorus agents run --name work --type codex -- resume # 백엔드를 재정의하고 `resume`을 그대로 전달

어느 에이전트인가 — --name <name|uuid>가 ~/.chorus/daemon.json의 agents[]에서 고릅니다. 에이전트가 하나뿐이면 생략할 수 있고, 여러 개면 --name을 전달(또는 CHORUS_AGENT_PROFILE 설정)해야 하며, 그러지 않으면 명령은 추측하지 않고 오류를 냅니다.
무엇이 주입되는가(실행되는 프로세스에만 주입되며, 셸에는 들어가지 않고 출력되지도 않습니다): CHORUS_URL, CHORUS_API_KEY, CHORUS_AGENT_PROFILE.
어느 바이너리인가 — 기본값은 에이전트에 저장된 백엔드이고 --type으로 재정의합니다. 종류는 각각 claude, codex, kiro-cli, pi, opencode, openclaw, dsh에 매핑됩니다. OpenCode / OpenClaw / DeepSeek Harness로 추가한 에이전트는 offline로 저장되므로(데몬이 자동으로 깨우지 않음), 실행하려면 --type을 명시하세요.
패스스루 — -- 뒤의 모든 것은 에이전트에 그대로 전달되어 에이전트의 모든 플래그를 쓸 수 있습니다. 에이전트는 사용자의 터미널을 이어받고, chorus agents run은 그 종료 코드로 종료합니다.

영구 args/env와 일회성 재정의

선택된 각 agents[] 항목에는 args(문자열 배열, 기본값 [])와 env(문자열을 문자열에 매핑하는 객체, 기본값 {})를 둘 수 있으며, 데몬 깨우기와 포그라운드 실행 모두 이 값을 사용합니다. agents[]가 비어 있지 않으면 각 항목은 최상위 args / env를 상속하지 않으며, 최상위에 이 값을 설정하면 오류가 됩니다. 복사해 쓸 수 있는 모델/사고/env 예제, 평면 파일 이전, 검증, 비밀 정보 취급 시 주의 사항은 데몬 가이드를 확인하세요.

값은 리터럴이며 셸 확장, dotenv 로딩, 비밀 조회를 하지 않습니다. env는 실행된 에이전트에만 영향을 줍니다. CHORUS_*와 Claude Code 중첩 변수 CLAUDECODE / CLAUDE_CODE_ENTRYPOINT는 대소문자와 무관하게 예약되어 있으며, 설정하면 조용히 무시되는 대신 오류가 발생합니다. 영구 인수는 Chorus가 관리하는 옵션(세션, 프롬프트, 프로토콜, 작업 디렉터리, MCP, 권한 제어)을 재정의할 수 없고, -- / - 구분자나 도움말·버전 정보만 출력하고 종료하는 플래그도 포함할 수 없습니다. 실행 시 명시적으로 전달한 인수는 네이티브 재개 명령을 포함해 그대로 전달됩니다. 이 검사는 알려진 충돌을 막기 위한 것이며 샌드박스가 아닙니다.

chorus agents run은 실행할 때마다 파일을 다시 읽지만, 데몬은 chorus daemon restart 후에만 변경 사항을 반영합니다. 어느 쪽이든 이미 실행 중인 에이전트에는 영향을 주지 않습니다. --type은 검증과 재정의 판정에 쓰는 백엔드를 선택할 뿐 백엔드 플래그를 변환하지 않습니다.

아래 옵션에 한해, 선택된 명령 범위에서 명시적으로 지정하면 구성된 같은 옵션과 그 값을 대체합니다.

실제 백엔드	인식하는 재정의
`claude-code` / `claude`	`--model`, `--effort`
`codex`	`--model` / `-m` / 구성 키 `model`; 구성 키 `model_reasoning_effort`
`kiro`	`--model`, `--effort`
`pi`	`--model`, `--thinking`, `--provider`
`opencode`	`--model` / `-m`
`openclaw`	`agent`의 `--model`, `--thinking`(`-m`은 모델이 아닌 메시지)
`dsh`	없음. 대신 `DSH_PROVIDER` / `DSH_MODEL` 환경 변수 사용

판정은 --option value, --option=value, 그리고 표에 -m이 있는 경우 -mVALUE / -m=VALUE를 인식합니다. Codex는 -c key=value, -ckey=value, -c=key=value, --config key=value, --config=key=value를 지원합니다. 표의 두 키만 우선순위 처리에 참여하며 무관한 구성 항목은 유지됩니다. 백엔드도 해당 표기를 지원해야 합니다. Pi 0.85.1의 --model, --thinking, --provider는 등호 형식 대신 값을 분리해서 전달하세요.

chorus agents run --name pi-worker -- --model anthropic/claude-sonnet-4-6 --thinking medium
chorus agents run --name codex-worker -- exec --model gpt-5.4 -c model_reasoning_effort=high

하위 명령: 영구 인수는 인식한 가장 깊은 명령 뒤에 삽입됩니다. 대상은 Codex의 exec, exec resume, resume, Kiro의 chat, OpenClaw의 agent입니다. 명시적 재정의도 같은 범위에 두세요. --model chosen exec가 아니라 exec --model chosen을 사용합니다. 하위 명령 앞에 둔 모델 옵션은 하위 명령에 구성된 모델을 대체하지 않습니다. Codex -c/--config 키는 범위와 관계없이 적용됩니다. 인식한 명령이 없으면 구성 인수를 맨 앞에 둡니다. 다른 명령 경로는 추론하지 않으므로, 그런 경로에서는 호환되지 않는 영구 인수를 빼고 네이티브 패스스루를 사용하세요.

알 수 없는 옵션:

영구 args는 일반적인 알 수 없는 플래그를 허용하지만, 다음 토큰이 값인지 프롬프트인지는 추측하지 못합니다. 백엔드가 지원하면 ["--future", "value"] 대신 ["--future=value"]를 사용하세요. 알려진 옵션에는 요구되는 값을 제공해야 합니다.
알 수 없는 옵션이나 반복 가능한 옵션은 선택된 범위 안에서 순서(구성 값 다음에 명시적 값)를 유지하며, 일반적인 “마지막 값 우선” 규칙은 보장되지 않습니다.
모호한 명시적 옵션(인라인 값이 없는 알 수 없는 옵션) 뒤에서는 Chorus가 재정의를 더 찾지 않습니다. 알려진 재정의를 그 앞에 두거나 지원되는 인라인 값을 사용하세요. 바깥쪽 Chorus 구분자를 제거한 뒤 에이전트 인수 안에서 처음 나오는 단독 --에서도 분석이 멈춥니다.
명령 탐색은 위치 인수로 된 프롬프트, 알 수 없는 명령, 모호한 옵션에서 멈추며, 알려진 옵션의 값은 건너뜁니다.
명시적 토큰은 모두 그대로 전달되므로 백엔드 플래그와 버전 호환성은 직접 확인하세요. Windows .cmd/.bat 제한은 데몬 가이드를 참고하세요.

Codex 데몬은 영구 인수를 모델 옵션과 허용된 -c / --config 설정으로 더 제한합니다. 다른 플래그는 포그라운드 세션에서는 동작하더라도, 데몬이 에이전트를 깨우기 전에 오류가 발생합니다. Codex 데몬 설정을 참고하세요.

셸에서 MCP 도구 호출하기 — `chorus mcp`

chorus mcp는 네이티브 MCP 클라이언트로, 스크립트나 터미널에서 어떤 Chorus 도구든 호출하는, 모델 토큰을 쓰지 않는 경로입니다. 이전의 chorus-api.sh / chorus-mcp-call.sh 래퍼를 대체합니다.

chorus mcp call <tool> '<json>'                  # call a tool with a JSON argument object
chorus mcp call <tool> --arg key=value           # set one string argument
chorus mcp call <tool> --arg-file content=<path> # stream a file's raw bytes into an argument
chorus mcp whoami                                 # print this agent's own UUID
chorus mcp list                                   # list the tools this agent may call

--arg-file는 문서 본문이나 OpenSpec 파일 같은 큰 내용을 모델에 다시 입력하지 않고 도구로 전달하는 방법입니다. 성공하면 chorus mcp call은 도구 결과를 stdout에 그대로 출력하고, 도구나 전송 오류는 0이 아닌 종료 코드와 함께 stderr로 나갑니다.

에이전트 신원은 다음 순서로 결정됩니다: --agent <name|uuid> → 명시적 --url + --api-key 플래그 → CHORUS_AGENT_PROFILE → CHORUS_URL + CHORUS_API_KEY → 구성된 에이전트가 하나뿐일 때 그 에이전트.

연결 환경 변수

변수	의미
`CHORUS_URL`	Chorus 인스턴스 URL.
`CHORUS_API_KEY`	에이전트 API 키(`cho_…`).
`CHORUS_AGENT_PROFILE`	사용할 구성된 에이전트의 이름 또는 UUID(선택). 설정되면 `chorus mcp`가 그 에이전트의 키를 `~/.chorus/daemon.json`에서 읽으므로, `CHORUS_API_KEY`를 내보낼 필요가 없습니다.

데몬이 깨운 세션은 CHORUS_AGENT_PROFILE를 자동으로 받습니다. 특정 구성 에이전트로 행동해야 하는 대화형 셸에서만 직접 설정하면 됩니다.

인증 정보는 어디로 가는가

chorus agents add는 검증된 인증 정보를 항상 ~/.chorus/daemon.json에 씁니다(권한 0600, 키는 절대 출력되지 않음). 네 에이전트에 대해서는 대화형 세션이 수동 내보내기 없이 인증하도록 그 에이전트 자신의 구성에도 인증 정보를 기록합니다.

에이전트	추가 인증 정보 저장소
Claude Code	`~/.claude/settings.json`의 `env` 블록(`CLAUDE_CONFIG_DIR`를 따름).
Codex	`~/.codex/.env`(`CODEX_HOME`을 따름). Codex는 keyless `config.toml` 항목을 통해 환경 변수에서 키를 읽습니다.
DeepSeek Harness	`$DSH_HOME/.env`.
Hermes	`$HERMES_HOME/.env`(기본 `~/.hermes/.env`, 모드 `0600`). 원격 MCP 설정에는 키 자리표시자를 저장합니다.

Kiro, OpenCode, OpenClaw는 자신의 설치된 구성에서, 또는 데몬이 깨운 Kiro의 경우에는 데몬이 깨울 때마다 내보내는 환경 변수에서 인증 정보를 읽습니다.

에이전트용

트리거. 이 페이지에 오는 이유는 CLI를 설치·업그레이드하거나, 에이전트를 구성하거나 (chorus agents add), 셸에서 Chorus 도구를 호출하기(chorus mcp call) 위해서입니다.
제약. 문서 미러와 그 밖의 큰 내용 호출에는 chorus mcp call <tool> '<json>' --arg-file content=<file>을 우선하고, chorus가 PATH에 없을 때만 chorus-api.sh / chorus-mcp-call.sh로 대체하세요. API 키를 명령줄이나 셸 기록에 절대 붙여 넣지 말고, chorus agents add / chorus login이 받아 가게 하세요.
출처. 정확한 플래그 목록은 chorus --help와 chorus <command> --help로 확인하세요. 항상 설치된 버전과 일치합니다.