CLI 명령어 레퍼런스

Herdr의 CLI는 통합 및 에이전트에서 사용하는 동일한 로컬 소켓 API를 통해 실행 중인 서버와 통신합니다.

대부분의 명령은 스크립트의 결정적 자동화를 위해 JSON 응답을 출력합니다.

herdr                         # launch or attach to the default session
herdr --remote workbox        # attach through SSH, using local keybindings
herdr --default-config        # print default config
herdr update                  # download and install from the configured channel
herdr completion zsh          # generate a zsh completion script
herdr channel show            # print stable or preview
herdr channel set preview     # opt into preview builds
herdr channel set stable      # return a direct install to stable
herdr --version               # print version

선택적 실행 및 업데이트 설정:

• 기본값 대신 명명된 세션을 사용하려면 --session <name>을 추가하세요.
• 로컬 키 설정 대신 서버 키 설정을 사용하려면 원격 연결에 --remote-keybindings server을 추가하세요.
• 실험적인 라이브 핸드오프에는 herdr --remote 또는 herdr update에 대한 명시적인 --handoff이 필요합니다. 일반적인 설정이나 연결 경로가 아닙니다. 업데이트를 참조하세요.

상태 명령:

herdr status
herdr status server
herdr status client

API 스키마 명령:

herdr api schema
herdr api schema --json
herdr api schema --output herdr-api.schema.json

herdr api schema은 설치된 바이너리와 함께 번들로 제공되는 소켓 프로토콜 스키마의 간략한 요약을 출력합니다. 전체 JSON 스키마 문서에는 --json을 사용하고, 해당 문서를 파일에 쓰려면 --output PATH를 사용하세요.

herdr machine list
herdr machine add workbox
herdr machine add workbox --label "Build machine"
herdr machine rename <profile-id> --label "New name"
herdr machine disable <profile-id>
herdr machine enable <profile-id>
herdr machine remove <profile-id>

대화형 터미널에서 machine add은 실행 중인 세션을 검색하고 여러 세션이 실행되는 시기를 선택할 수 있도록 합니다. 실행 중인 세션이 없거나 Herdr 설치가 없으면 default을 사용합니다. 설치된 바이너리에 대해 실패한 쿼리에는 명시적인 선택이 필요합니다. 검색을 건너뛰려면 --remote-session <name>를 추가하세요. 비대화형 명령은 해당 플래그가 제공되지 않는 한 default을 사용합니다. machine list는 스크립트에 대해 선택적 --json을 허용합니다. 전체 설정 및 연결 가이드는 기기 연결을 참조하세요.

machine add은 원격 설치 기능을 확인하고, 필요한 경우에만 승인을 받아 설치 또는 업데이트하고, 저장하기 전에 요청한 세션의 백그라운드 서버를 시작합니다. 호환되는 릴리스 버전이 일치할 필요는 없습니다. 설치 또는 다시 시작 승인이 필요한 경우 대화형 터미널에서 설정을 실행하세요. 실패하거나 취소된 설정은 프로필을 저장하지 않습니다. 실행 중인 서버를 교체하려면 기본 응답이 아니요인 명시적인 승인이 필요하며 해당 패널 프로세스가 중지됩니다. machine add은 암시적으로 실험적 핸드오프를 활성화하지 않습니다.

변경 사항은 일반적으로 1초 이내에 로컬 Herdr 클라이언트를 열 때 자동으로 적용됩니다. 추가되거나 활성화된 컴퓨터는 백그라운드에서 연결됩니다. 이름을 바꾸면 다시 연결되지 않습니다. 제거하거나 비활성화하면 해당 시스템만 연결 해제되고 원격 세션은 계속 실행됩니다. 보고 있는 기기을 제거하면 로컬로 돌아가거나 다시 연결될 때까지 로컬을 사용할 수 없는 것으로 표시됩니다. 각 프로필은 불투명 ID, 레이블, SSH 대상, 명시적 원격 세션 및 클라이언트 상태의 활성화 상태를 저장합니다. Herdr는 비밀번호, 개인 키 또는 기타 SSH 자격 증명을 저장하지 않습니다.

새로운 비대화형 SSH 및 원격 Herdr 검사를 위해 herdr machine status [<label-or-id>] [--json]을 사용하세요. reachable은 TUI의 현재 연결이 아닌 이 확인을 설명합니다. SSH 인증 및 확인을 위해 터미널에서 herdr machine reconnect <label-or-id>를 사용하세요. Herdr를 설치하거나 업데이트하지 않습니다. 열린 클라이언트는 30초 이내에 실패한 연결을 다시 시도합니다. ! auth 또는 ! error를 클릭하면 최신 오류 및 CLI 지침이 표시됩니다. 접힌 사이드바에는 !이 표시됩니다. 플랫폼 제한은 SSH 인증 복구을 참조하세요. 원격 설정의 경우 herdr --remote workbox을 사용하고 명명된 세션에만 --session <name>을 추가합니다.

작업 공간, 탭, 패널 ID 및 에이전트 이름은 단일 서버에 속합니다. UI에서 기기을 선택해도 CLI 명령의 대상이 변경되지 않습니다. 전역 prefix --machine <label-or-id>를 사용하여 API 명령을 저장된 SSH 시스템으로 라우팅합니다.

herdr --machine "Build machine" agent list
herdr --machine <profile-id> pane list
herdr --machine "Build machine" agent prompt w1:p1 "review this change"
herdr --machine "Build machine" worktree create --cwd /srv/project --branch review

선택기는 임의의 SSH 호스트 이름이 아닌 활성화된 저장된 프로필 ID 또는 대소문자를 구분하는 고유한 라벨과 일치해야 합니다. 저장된 원격 세션이 사용됩니다. --machine을 --session 또는 --remote과 결합하면 오류가 발생합니다. 프리픽스가 없으면 명령은 기존 로컬 세션/소켓 동작을 유지합니다.

지원되는 명령은 workspace, worktree, tab, pane, notification, agent(attach 및 로컬 explain --file 제외), api snapshot, status server 및 API 지원 플러그인 명령(link, unlink, enable, disable, list, action, log, pane). 서버 명령은 stop, reload-config, agent-manifests 및 reload-agent-manifests을 지원합니다. 로컬 설치/구성 명령, 플러그인 설치, 세션 관리 및 대화형 터미널 연결은 전달되지 않습니다.

요청과 응답은 비대화형 SSH를 통해 JSON API를 통해 이동합니다. API 페이로드는 SSH 셸 명령에 삽입되지 않습니다. 개방형 TUI가 필요하지 않으며 브리지는 서버를 설치, 시작 또는 다시 시작하지 않습니다. 기기 전달을 지원하고 실행 중인 원격 서버의 API 프로토콜 호환성을 유지하도록 로컬 CLI 및 원격 Herdr 설치를 업데이트합니다. 인증, 사용할 수 없는 시스템 및 호환되지 않는 버전은 로컬로 대체되지 않고 실패합니다. 연결 실패 후 요청이 자동으로 재시도되지 않습니다.

로컬 패널 ID는 원격 명령으로 상속되지 않습니다. 명시적인 원격 ID를 사용하십시오. --current은 호출자의 로컬 패널을 참조할 수 없습니다. 원격 작업 트리 경로는 절대 경로, ~이거나 ~/(서버에서 확장됨)로 시작해야 합니다. 플러그인 링크 경로는 절대적이어야 합니다. 프리픽스는 한 번에 하나의 시스템을 대상으로 합니다. 다른 TUI 연결을 통한 결합 목록 및 라우팅은 포함되지 않습니다.

herdr completion zsh
herdr completions zsh
herdr completion bash
herdr completion fish
herdr completion powershell
herdr completion elvish

completion은 스크립트를 stdout으로 출력합니다. completions은 별칭입니다. 임시 zsh 세션의 경우 스크립트를 직접 로드합니다.

source <(herdr completion zsh)

지속적인 zsh 설정의 경우 compinit가 실행되기 전에 fpath 어딘가에 생성된 _herdr 함수를 작성합니다.

mkdir -p ~/.zfunc
herdr completion zsh > ~/.zfunc/_herdr

그런 다음 .zshrc에 다음이 포함되어 있는지 확인하세요.

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

herdr server
herdr server stop
herdr server reload-config
herdr server agent-manifests [--json]
herdr server update-agent-manifests [--json]
herdr server reload-agent-manifests

herdr server은 헤드리스 서버를 명시적으로 실행합니다. 감독형 또는 서비스 스타일 설정에 사용하세요. reload-config은 패널을 다시 시작하지 않고 다시 로드 가능한 설정을 적용합니다. agent-manifests는 활성 에이전트 감지 매니페스트 소스, 캐시된 원격 버전 및 마지막 원격 업데이트 결과를 보여줍니다. update-agent-manifests은 원격 매니페스트 업데이트를 즉시 가져와 실행 중인 서버에 다시 로드하고 업데이트된 매니페스트 상태를 출력합니다. 원시 상태 응답에 --json를 전달합니다. reload-agent-manifests는 로컬 재정의 편집 후 실행 중인 서버에 에이전트 감지 매니페스트를 다시 로드합니다.

herdr notification show <title> [--body TEXT] [--position top-left|top-right|bottom-left|bottom-right] [--sound none|done|request]

notification show은 구성된 [ui.toast] 전달을 사용합니다. --position은 인앱 Herdr 토스트에만 영향을 미칩니다. --sound의 기본값은 none입니다. done 및 request은 알림이 표시될 때만 기존 완료 및 주의 필요 소리를 재생합니다.

herdr session list [--json]
herdr session attach <name>
herdr session stop <name> [--json]
herdr session delete <name> [--json]

기본 세션을 명시적으로 중지해야 하는 경우 세션 이름으로 default을 사용합니다.

herdr workspace list
herdr workspace create [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
herdr workspace get <workspace_id>
herdr workspace focus <workspace_id>
herdr workspace rename <workspace_id> <label>
herdr workspace report-metadata <workspace_id> --source ID [--token NAME=VALUE] [--clear-token NAME] [--seq N] [--ttl-ms N]
herdr workspace close <workspace_id> [--group]

초점을 빼앗지 않고 작업 공간을 만드세요:

herdr workspace create --cwd ~/project --label api --no-focus

작업 공간은 최상위 프로젝트 또는 작업 컨텍스트입니다. 하나를 만들면 첫 번째 탭과 루트 창도 생성됩니다. JSON 응답은 해당 ID를 .result.workspace.workspace_id, .result.tab.tab_id 및 .result.root_pane.pane_id로 노출합니다.

herdr worktree list [--workspace ID | --cwd PATH] [--trust-repository]
herdr worktree create [--workspace ID | --cwd PATH] [--branch NAME] [--base REF] [--path PATH] [--label TEXT] [--focus] [--no-focus] [--trust-repository]
herdr worktree open [--workspace ID | --cwd PATH] (--path PATH | --branch NAME) [--label TEXT] [--focus] [--no-focus] [--trust-repository]
herdr worktree remove --workspace ID [--force] [--trust-repository]

Worktree는 Git 체크아웃 출처가 있는 일반적인 Herdr 작업 공간입니다. worktree create은 Git 작업 트리 체크아웃을 생성하고 이를 작업 공간으로 열고 상위 저장소 작업 공간과 그룹화합니다. --branch이 기존 로컬 지점의 이름을 지정하면 Herdr가 이를 확인합니다. 그렇지 않으면 --base 또는 HEAD에서 분기를 만듭니다. --path가 없으면 Herdr는 <worktrees.directory>/<repo>/<branch-slug> 아래에 결제를 생성합니다.

workspace close은 Herdr 상태만 닫습니다. 연결된 작업 트리 작업 공간이 열려 있는 동안 기본 작업 공간을 닫으려면 --group이 필요합니다. 이것이 없으면 명령은 그룹을 열어두고 workspace_group_close_required를 반환합니다. 결제를 삭제하려면 worktree remove을 실행하세요. git worktree remove를 실행하고 브랜치를 삭제하지 않으며 Git이 더티 체크아웃을 거부하면 --force이 필요합니다.

Git은 기본적으로 다른 사용자가 소유한 저장소를 거부합니다. 저장소를 독립적으로 확인한 경우 --trust-repository을 전달하여 해당 명령에 대해서만 확인된 경로를 신뢰하십시오. Herdr는 Git 구성을 변경하지 않습니다.

herdr tab list [--workspace <workspace_id>]
herdr tab create [--workspace <workspace_id>] [--cwd PATH] [--label TEXT] [--env KEY=VALUE] [--focus] [--no-focus]
herdr tab get <tab_id>
herdr tab focus <tab_id>
herdr tab rename <tab_id> <label>
herdr tab close <tab_id>

탭은 작업 공간 내의 또 다른 터미널 레이아웃입니다. --workspace이 없으면 tab create은 활성 작업 공간을 사용하고 아무것도 없으면 실패합니다. JSON 응답은 .result.tab.tab_id 및 .result.root_pane.pane_id을 노출합니다. 작업 공간의 마지막 탭을 닫으면 TUI 탭 닫기 작업과 일치하여 작업 공간도 닫힙니다. confirm_close가 활성화되어 있고 탭을 닫으면 전체 작업 트리 그룹도 닫히는 경우 tab close는 대신 confirmation_required 오류를 반환합니다.

ui.confirm_close을 활성화하면 TUI는 키 설정이나 탭 메뉴에서 작업 공간의 마지막 탭을 닫기 전에 확인을 요청합니다. 일반 CLI/API 탭은 즉시 닫힙니다.

작업 공간 및 탭 생성, 패널 분할은 기본적으로 포커스를 변경하지 않고 그대로 둡니다. --focus은 새 레이아웃을 선택합니다. --no-focus은 기본값을 명시적으로 나타냅니다. --cwd가 없으면 새 터미널은 기본적으로 소스 패널이나 작업 공간을 따르는 구성된 terminal.new_cwd 정책을 따릅니다. 각 --env KEY=VALUE는 새 루트 셸에서 해당 변수를 추가하거나 대체합니다.

herdr pane list [--workspace <workspace_id>]
herdr pane current [--pane ID|--current]
herdr pane get <pane_id>
herdr pane layout [--pane ID|--current]
herdr pane process-info [--pane ID|--current]
herdr pane neighbor --direction left|right|up|down [--pane ID|--current]
herdr pane edges [--pane ID|--current]
herdr pane focus --direction left|right|up|down [--pane ID|--current]
herdr pane resize --direction left|right|up|down [--amount FLOAT] [--pane ID|--current]
herdr pane zoom [<pane_id>|--pane ID|--current] [--toggle|--on|--off]
herdr pane rename <pane_id> <label>|--clear
herdr pane input [<pane_id>|--pane ID|--current] --right-click herdr|pane
herdr pane split [<pane_id>|--pane ID|--current] --direction right|down [--ratio FLOAT] [--cwd PATH] [--env KEY=VALUE] [--right-click herdr|pane] [--focus] [--no-focus]
herdr pane swap --direction left|right|up|down [--pane ID|--current]
herdr pane swap --source-pane ID --target-pane ID
herdr pane move <pane_id> --tab <tab_id> --split right|down [--target-pane ID] [--ratio FLOAT] [--focus|--no-focus]
herdr pane move <pane_id> --new-tab [--workspace ID] [--label TEXT] [--focus|--no-focus]
herdr pane move <pane_id> --new-workspace [--label TEXT] [--tab-label TEXT] [--focus|--no-focus]
herdr pane close <pane_id>

--current을 허용하는 패널 명령의 경우 Herdr는 명령이 Herdr 패널 내에서 실행될 때 호출 패널의 HERDR_PANE_ID을 사용합니다. pane split의 경우 명시적인 패널 ID 또는 --pane ID이 해당 패널을 분할합니다. 생략된 대상은 HERDR_PANE_ID를 사용할 수 있을 때 호출 패널을 분할하고, 그렇지 않으면 초점이 맞춰진 패널을 분할합니다. --current에는 호출 패널이 필요하며 HERDR_PANE_ID을 사용할 수 없는 경우 오류가 발생합니다. 분할 응답은 새 패널 ID를 .result.pane.pane_id로 노출합니다.

pane input --right-click pane은 수정되지 않은 오른쪽 클릭 제스처를 마우스 보고 패널 응용 프로그램으로 전달합니다. herdr은 기본 패널 메뉴를 복원합니다. 패널 프레임을 마우스 오른쪽 버튼으로 클릭하면 여전히 Herdr의 메뉴가 열립니다. pane split --right-click pane는 생성 시 새 패널에 동일한 정책을 적용합니다.

pane move 이후에는 이후 명령에 .result.move_result.pane.pane_id을 사용합니다. 작업 공간 간 이동은 작업 공간 한정 패널 ID를 변경합니다. 이전 값은 .result.move_result.previous_pane_id로 유지됩니다. 실행 중인 프로세스는 시작 시간을 HERDR_PANE_ID, HERDR_TAB_ID 및 HERDR_WORKSPACE_ID로 유지합니다. Herdr는 이전 패널 ID를 해당 터미널의 별칭으로 유지하므로 --current을 사용하는 패널 명령은 여전히 ​​이를 해결합니다. 라이브 에이전트 이름은 터미널을 따르며 이동 후에도 계속 확인됩니다.

출력 읽기:

herdr pane read <pane_id> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi] [--raw]
herdr pane read <pane_id> --source visible --ansi
herdr pane read <pane_id> --source recent-unwrapped --lines 120

pane read은 UTF-8 터미널 텍스트를 직접 출력합니다. ANSI 이스케이프는 기본적으로 제거됩니다. 소스가 스타일을 노출하는 위치를 유지하려면 --format ansi 또는 --ansi을 사용하십시오. detection 소스는 항상 일반 텍스트입니다. 최근 소스의 경우 --lines N는 선택적 언래핑 전에 마지막 N 렌더링된 터미널 행을 선택합니다. 그렇지 않으면 기본값을 80행으로 읽습니다. visible 및 detection의 경우 --lines을 생략하면 전체 스냅샷이 반환되지만 이를 지정하면 줄 바꿈으로 구분된 마지막 N줄이 유지됩니다. agent read은 동일한 출력 및 라인 동작을 사용합니다.

입력 보내기:

herdr pane send-text <pane_id> <text>
herdr pane send-keys <pane_id> <key> [key ...]
herdr pane run <pane_id> <command>

<key>은 Herdr 키-콤보 구문을 사용합니다. a과 같은 일반 출력 가능한 키, enter, tab, esc, backspace, left, right, up 및 down와 같은 특수 키, ctrl+h, control+j, alt+x 및 shift+tab과 같은 수정 코드, 기능 키 f1 등, minus, plus, backtick 등 구두점을 지정합니다. 레거시 C-c 및 c-c은 ctrl+c의 별칭으로 허용됩니다. esc은 표준 철자법입니다. escape도 허용됩니다.

pane run은 대괄호로 묶은 붙여넣기 모드를 존중하고 텍스트와 Enter를 자동으로 제출합니다. 명령의 경우 send-text과 send-keys Enter보다 선호합니다. 별도의 전송 작업은 낮은 수준으로 유지되며 제출되지 않습니다.

사용자 정의 훅에서 에이전트 상태를 보고합니다.

herdr pane report-agent <pane_id> \
  --source ID \
  --agent LABEL \
  --state idle|working|blocked|unknown \
  [--message TEXT] \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH] \
  [-- RESUME_COMMAND...]


herdr pane report-agent-session <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N] \
  [--agent-session-id ID] \
  [--agent-session-path PATH] \
  [--session-start-source SOURCE] \
  [-- RESUME_COMMAND...]


herdr pane release-agent <pane_id> \
  --source ID \
  --agent LABEL \
  [--seq N]

report-agent-session은 수명 주기 상태를 보고하지 않고 기본 세션 ID를 업데이트합니다. release-agent은 에이전트 프로세스가 종료될 때 해당 소스의 수명 주기 권한을 종료합니다.

-- 뒤의 인수는 Herdr가 서버를 다시 시작한 후 이 세션을 재개하기 위해 실행하는 명령입니다. 첫 번째 인수는 PATH의 일반 명령 이름이어야 하며 인수에는 아포스트로피가 포함될 수 없습니다.

pane get, pane list, agent get 및 agent list에는 공식 통합이 기본 세션 참조를 보고한 경우 읽기 전용 agent_session 개체가 포함됩니다. 기본 세션 참조가 저장되지 않은 경우 필드가 생략됩니다.

Herdr가 패널을 제어하는 전경 프로세스의 cwd를 확인할 수 있는 경우 이러한 명령에는 foreground_cwd이 포함됩니다. cwd 필드는 라벨 및 후속 cwd 동작에 사용되는 창/작업 공간 cwd로 유지됩니다.

터미널 스크롤 메트릭을 사용할 수 있는 경우 pane get 및 pane list에는 scroll가 포함됩니다. scroll.offset_from_bottom == 0은 패널이 스크롤백 하단에 있음을 의미합니다.

의미 상태를 인계받지 않고 표시 전용 패널 메타데이터를 보고합니다.

herdr pane report-metadata <pane_id> \
  --source ID \
  [--agent LABEL] \
  [--applies-to-source ID] \
  [--title TEXT|--clear-title] \
  [--display-agent TEXT|--clear-display-agent] \
  [--state-label STATUS=TEXT] \
  [--clear-state-labels] \
  [--token NAME=VALUE] \
  [--clear-token NAME] \
  [--seq N] \
  [--ttl-ms N]

STATUS은(는) idle, working, blocked, done 또는 unknown 중 하나입니다. --agent 및 --applies-to-source은 --title, --display-agent 및 --state-label만 보호합니다. 토큰 패치를 보호하지 않습니다. 토큰 보고자는 자체 삭제 또는 TTL 새로 고침을 수행합니다. 표시되는 이름을 변경하려면 --display-agent을 사용하십시오.

메타데이터 텍스트는 저장 전에 정규화됩니다. Herdr는 주변 공백을 자르고 제어 문자를 제거하고 --title, --display-agent, 각 --state-label 및 토큰 값을 80자로 제한합니다. 정규화된 빈 토큰 값은 해당 키를 지웁니다.

--token은 명명된 표시 값 하나를 패치합니다. --clear-token은 하나를 제거합니다. 언급되지 않은 토큰은 변경되지 않습니다. 패널 토큰은 에이전트 사이드바 행에서 $name로 사용할 수 있습니다. 작업 공간 토큰은 Space 행에서 사용할 수 있습니다. TTL은 해당 호출로 업데이트된 토큰 키에 독립적으로 적용됩니다.

--source 및 --applies-to-source은 80자 이하여야 하며 ASCII 문자, 숫자, 콜론, 점, 밑줄 및 하이픈만 포함할 수 있습니다. --ttl-ms는 메타데이터가 자동으로 만료되도록 하며 1에서 86400000밀리초 사이여야 합니다. 대체되거나 지워지거나 패널이 닫힐 때까지 유지되어야 하는 메타데이터에 대해서는 이를 생략합니다. --seq를 사용하면 Herdr가 동일한 --source의 오래된 보고서를 무시할 수 있습니다. 오래된 보고서는 API에서 허용되지만 패널 상태에서는 무시됩니다. 패널 또는 작업 공간은 수명 동안 최대 32개의 개별 소스로부터 순서화된 토큰 보고서를 허용합니다. 지우거나 만료해도 해당 소스 슬롯은 해제되지 않습니다.

창 대 에이전트 모델 및 전체 오케스트레이션 예제는 에이전트 자동화을 참조하세요.

herdr agent list
herdr agent get <target>
herdr agent read <target> [--source visible|recent|recent-unwrapped|detection] [--lines N] [--format text|ansi] [--ansi]
herdr agent send-keys <target> <key> [key ...]
herdr agent prompt <target> <text> [--wait] [--until STATUS]... [--timeout MS]
herdr agent rename <target> <name>|--clear
herdr agent focus <target>
herdr agent wait <target> [--until STATUS]... [--timeout MS]
herdr agent attach <target> [--takeover]
herdr agent start <name> --kind KIND --pane ID [--timeout MS] [-- <agent-args...>]
herdr agent explain <target> [--json|--verbose]
herdr agent explain --file PATH --agent LABEL [--json|--verbose]

에이전트 대상은 고유한 라이브 에이전트 이름이거나 현재 에이전트를 호스팅하는 패널 ID입니다. 터미널 ID와 기본 에이전트 종류 레이블은 에이전트 대상이 아닙니다. agent start을 통해 시작된 에이전트에는 이름이 필요합니다. 수동으로 시작된 에이전트는 이름이 지정되지 않은 상태로 유지되며 해당 패널 ID를 사용합니다.

agent start은 사용 가능한 기존 셸 패널을 활성화합니다. 패널의 대화형 셸은 실행 중인 전경 명령, 편집기 또는 에이전트 없이 전경을 소유해야 합니다. 토폴로지는 별도로 생성해야 합니다. 이름은 라이브 에이전트 간에 고유하며 [a-z][a-z0-9_-]{0,31}과 일치해야 합니다. 종류는 Herdr의 표준 대화형 실행 파일을 선택하고 -- 이후의 인수는 해당 실행 파일에 전달됩니다. 지원되는 종류는 pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, letta, maki 및 muse. 이름은 현재 패널 점유자를 따르며 해당 에이전트가 종료되거나 해제되거나 교체되면 지워집니다. 일시적인 감지 불확실성은 이를 제거하지 않습니다.

성공적인 시작은 예상 에이전트가 동일한 터미널을 소유하고 대화형 입력이 준비된 후에만 반환됩니다. 시작 중에 감지가 blocked을 보고하면 명령은 즉시 agent_not_ready을 반환합니다. 이름은 agent read 및 agent send-keys에 계속 사용할 수 있으며 idle 감지 보고 후 프롬프트를 표시할 준비가 됩니다. 기본 시작 시간 제한은 30000밀리초입니다. 명시적 값은 3000보다 크고 300000 이하여야 합니다.

agent prompt은(는) 라이브 대괄호 붙여넣기 모드를 존중하고 에이전트가 작업하는 동안을 포함하여 하나의 주문된 제출로 지연된 Enter가 뒤따르는 텍스트를 씁니다. --wait 없이 성공하면 턴의 시작이 아니라 쓰기를 인식합니다. Windows에서 Codex는 Enter 전에 붙여넣기 경계를 수신하므로 제출은 프롬프트 크기에 의존하지 않습니다. 호출자 시간 초과에는 제출 시간이 포함됩니다. 에이전트가 이미 blocked인 경우 입력을 보내지 않고 agent_blocked을 반환합니다. --wait를 사용하면 다른 비작업 상태에서 전송된 프롬프트는 제출 후 최대 5초 동안 관찰된 working 또는 blocked 상태를 생성하거나 Herdr가 agent_prompt_stalled을 반환합니다. 호출자 시간 초과가 먼저 만료되면 Herdr는 일반적인 timeout 오류를 반환합니다. 이렇게 하면 관련되지 않은 idle, done 또는 세션 변경이 대기를 완료하는 것을 방지할 수 있습니다. 활동이 관찰된 후 처음 요청된 정착 상태를 기다립니다. 개별 회전을 추적하지 않습니다. 에이전트가 이미 작업 중인 경우 활성 턴을 완료하면 대기 시간이 충족될 수 있습니다. --until은 일치 상태를 좁히고 --wait도 존재하지 않는 한 거부됩니다. 독립형 agent wait은 현재 상태가 일치하면 즉시 반환됩니다. 둘 다 기본값은 idle, done 또는 blocked입니다. 필요한 경우 --until unknown을 명시적으로 사용하세요.

idle 및 done은 모두 입력 준비가 되었음을 의미합니다. CLI/API는 서버의 확인된 상태를 사용합니다. done는 유휴 상태이지만 아직 확인된 것으로 표시되지 않았습니다. 명시적인 pane focus / agent focus 명령은 대상을 확인된 것으로 표시하고 읽기는 수행하지 않습니다. 각 TUI 클라이언트는 조회된 완료를 독립적으로 추적하므로 완료 배지는 CLI 또는 다른 클라이언트와 다를 수 있습니다. blocked는 Herdr가 승인 또는 질문 UI를 인식했음을 의미합니다. unknown은 에이전트가 있지만 Herdr가 이를 자신있게 분류할 수 없음을 의미하며 작업이 성공했다는 의미는 아닙니다.

agent send-keys은 enter, up, esc 또는 ctrl+c와 같은 논리적 터미널 키를 보냅니다. Herdr는 바이트를 쓰기 전에 모든 키의 유효성을 검사합니다. agent read는 확인된 터미널 스트림을 읽고 agent rename은 이미 감지된 에이전트의 이름을 지정합니다.

agent explain은 실행 중인 서버에 화면 감지에 사용되는 것과 동일한 하단 버퍼 감지 스냅샷을 분류하도록 요청하므로 실시간 출력에 서버의 활성 매니페스트 캐시가 반영됩니다. agent.explain 소켓 방식을 사용하기 때문에 Live explain을 사용하기 전에 Herdr를 업그레이드한 후 업데이트된 서버를 다시 시작하거나 넘겨주세요. 대신에 저장된 테스트 픽스처를 로컬로 설명하려면 --file PATH --agent LABEL를 사용하십시오. 기본 출력에는 에이전트, 최종 상태, 매니페스트 소스 및 버전, 해당 화면 영역의 근거와 일치하는 규칙, 대체, 건너뛰기 또는 경고 이유가 표시됩니다. 표시되는 증거 플래그, 캐시된 원격 버전, 로컬 재정의 섀도잉, 원격 업데이트 상태 및 일치자 및 화면 영역의 근거가 포함된 전체 평가 규칙 목록에 대해 --verbose을 추가합니다. 문제 보고 또는 테스트를 위해 --json를 추가하세요.

일반 터미널, 서버, 테스트, 셸 또는 하위 수준 터미널 제어에는 pane send-text, pane send-keys, pane run 및 terminal attach을 사용합니다. Enter를 사용하여 명령을 제출하려면 pane run을 사용하십시오.

herdr terminal attach <terminal_id> [--takeover]
herdr terminal session control <target> [--takeover] [--cols N] [--rows N]
herdr terminal session observe <target> [--cols N] [--rows N]
herdr terminal title set <title>
herdr terminal title clear

ctrl+b q을 사용하여 직접 연결에서 분리합니다. ctrl+b ctrl+b와 함께 리터럴 ctrl+b을 보냅니다. terminal session control은 패널, 터미널 또는 에이전트 대상에 대해 쓰기 가능한 라이브 터미널 스트림을 엽니다. 관찰 모드와 동일한 개행으로 구분된 terminal.frame 및 terminal.closed 레코드를 출력합니다. stdin에서 개행으로 구분된 JSON 명령(terminal.input, terminal.resize, terminal.scroll, terminal.mouse 및 terminal.release)을 읽습니다. 한 번에 하나의 컨트롤러가 터미널을 소유할 수 있습니다. --takeover을 사용하여 교체하세요. terminal.mouse는 컨트롤러 뷰포트의 0 기반 셀에서 하나의 마우스 이벤트를 보냅니다(예: {"type":"terminal.mouse","action":"down","button":"left","column":12,"row":5}). action은(는) down, up, drag 또는 move입니다. button는 left(기본값), right 또는 middle입니다. modifiers은 선택 사항이며 Shift = 1, Ctrl = 2 및 Alt = 4(기본값 0)를 결합합니다. 클릭은 down 다음에 up입니다. Herdr는 응용 프로그램의 마우스 모드에 대한 이벤트를 인코딩하고 응용 프로그램이 마우스 보고를 활성화하지 않은 경우 이를 삭제하므로 일반 쉘은 잘못된 입력을 받지 않습니다. move은 모든 마우스 동작을 추적하는 응용 프로그램에만 도달합니다. terminal session observe은 패널, 터미널 또는 에이전트 대상에 대한 읽기 전용 라이브 터미널 스트림을 엽니다. 줄 바꿈으로 구분된 JSON terminal.frame 레코드를 base64로 인코딩된 ANSI 바이트로 출력한 다음 서버가 스트림을 닫을 때 terminal.closed 레코드를 출력합니다. 여러 관찰자가 입력, 크기 조정, 스크롤 또는 인수 권한을 받지 않고도 동일한 터미널을 볼 수 있습니다. Linux 및 macOS에서는 소켓 쓰기가 30초 동안 진행되지 않으면 관찰자의 연결이 끊어집니다. 정지된 스트림은 최종 terminal.closed 레코드 없이 끝날 수 있습니다. 패널과 다른 클라이언트는 계속 실행됩니다. 조용한 패널에서는 이 시간 초과가 발생하지 않습니다. terminal title clear은 외부 터미널 패널 제목을 ui.window_title에게 다시 전달합니다.

패널에서 출력을 기다립니다.

herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

일반 명령 및 서버에는 pane wait-output을 사용합니다. 코딩 에이전트에는 agent wait을 사용하세요.

pane wait-output은 이미 존재하는 출력을 포함하여 선택한 스냅샷을 즉시 확인한 다음 일치할 때까지 폴링합니다. 기본 소스 이름은 recent입니다. 일치는 이를 최신 80개의 렌더링된 터미널 행에서 래핑되지 않은 최근 출력으로 처리합니다. --lines는 해당 행 제한을 변경합니다. --match은 한 줄에서 리터럴 하위 문자열을 찾고, --regex는 Rust 정규식 구문을 사용하며 한 번에 한 줄씩 일치합니다.

시간 초과 또는 agent_prompt_stalled은 프롬프트가 전달되지 않았다는 것을 증명하지 않습니다. 다시 시도하기 전에 에이전트를 검사하세요.

pane wait-output 및 agent wait은 --timeout이 생략되면 무기한 대기합니다. agent prompt --wait의 경우 활동이 관찰된 후 또는 working에서 프롬프트가 시작될 때 정착 상태 대기가 무기한입니다. 작동하지 않는 프롬프트는 관찰된 활동 없이 5초 후에도 여전히 agent_prompt_stalled를 반환합니다. 종료 상태 1의 stderr에서 시간 초과 또는 서버 오류가 JSON으로 내보내집니다. CLI 사용 오류는 상태 2로 종료됩니다.

herdr integration install pi
herdr integration install omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install devin
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install qwen
herdr integration install letta
herdr integration install cursor
herdr integration install mastracode
herdr integration install grok
herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall devin
herdr integration uninstall droid
herdr integration uninstall kimi
herdr integration uninstall opencode
herdr integration uninstall kilo
herdr integration uninstall hermes
herdr integration uninstall qodercli
herdr integration uninstall qwen
herdr integration uninstall letta
herdr integration uninstall cursor
herdr integration uninstall mastracode
herdr integration uninstall grok
herdr integration status [--outdated-only]

플러그인 명령은 로컬 실행 가능 워크플로 플러그인을 설치하고 실행합니다. 플러그인은 매니페스트에 프로세스 외부 명령을 더한 것입니다. Herdr는 호스트 표면을 소유하고 플러그인은 구현 언어를 소유합니다.

플러그인을 설치, 나열 및 제거합니다.

herdr plugin install <owner>/<repo>[/subdir...] [--ref REF] [--yes]
herdr plugin list [--plugin ID] [--json]
herdr plugin uninstall <plugin_id|owner/repo[/subdir...]>
herdr plugin enable <plugin_id>
herdr plugin disable <plugin_id>

plugin install은 ogulcancelik/herdr-plugin-examples/worktree-bootstrap과 같은 GitHub 단축어만 허용합니다. git를 사용하고, 대화형 터미널에 신뢰 미리 보기를 표시하고, 지원되는 매니페스트 빌드 명령을 실행하고, Herdr 관리 디렉터리에 GitHub 설치를 저장합니다. 비대화형 설치에는 --yes을 사용하세요. GitHub 관리 플러그인을 다시 설치하면 해당 관리 체크아웃이 대체됩니다. 로컬로 연결된 플러그인을 통한 설치는 거부됩니다. 플러그인 매니페스트는 min_herdr_version를 선언해야 합니다. 플러그인에 최신 Herdr 바이너리가 필요한 경우 설치 및 링크가 실패합니다. plugin list은 기본적으로 사람이 읽을 수 있습니다. 원시 API 응답에 --json을 전달합니다.

플러그인 설치 및 활성화 상태는 현재 사용자에게 전역적으로 적용됩니다. 하나의 Herdr 세션을 통해 설치, 연결, 활성화 또는 비활성화된 플러그인은 모든 세션에서 동일한 상태로 즉시 사용할 수 있습니다.

지역 개발:

herdr plugin link <path> [--disabled]
herdr plugin unlink <plugin_id>

plugin link은 herdr-plugin.toml 또는 직접 매니페스트 경로를 포함하는 플러그인 디렉터리를 허용합니다. 로컬 체크아웃에서 플러그인을 작성하거나 테스트하는 동안 사용하세요. plugin unlink는 플러그인 등록을 취소하고 파일을 그대로 둡니다. plugin uninstall은 플러그인 등록을 취소하고 Herdr가 관리하는 GitHub 체크아웃 파일도 제거합니다. GitHub 설치의 경우 제거는 플러그인 ID 또는 설치에 사용된 것과 동일한 owner/repo[/subdir...] 약어를 허용합니다. 작업, 이벤트 훅, 패널 및 링크 처리기는 매니페스트에 선언됩니다. 런타임 작업 등록은 v1의 일부가 아닙니다.

구성 디렉터리:

herdr plugin config-dir <plugin_id>

plugin config-dir은 플러그인의 구성 디렉터리를 출력합니다. 필요한 경우 디렉터리를 생성하고 레거시 플러그인 구성 위치가 있는 경우 해당 디렉터리를 시드합니다. 설정 문서 및 셸 스크립트에서 이를 사용하여 관리형 플러그인 체크아웃과 별도로 .env 파일 및 기타 사용자 편집 가능한 구성에 대한 안정적인 경로를 사용자에게 알려줍니다.

작업:

herdr plugin action list [--plugin ID]
herdr plugin action invoke <action_id> [--plugin ID]

plugin action invoke은 설치되어 활성화된 플랫폼 호환 플러그인 작업에 대한 매니페스트 명령을 시작하고 시작된 명령 로그 기록을 JSON 응답으로 출력합니다. 둘 이상의 플러그인이 동일한 작업 ID를 사용하는 경우 정규 작업 ID(plugin.id.action)를 사용하세요. 로컬 작업 ID에는 점이 포함될 수 없으므로 플러그인 ID에 점이 포함되어 있어도 정규화된 ID는 명확하게 유지됩니다.

로그:

herdr plugin log list [--plugin ID] [--limit N]

관리되는 터미널 창:

herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
herdr plugin pane focus <pane_id>
herdr plugin pane close <pane_id>

plugin pane open을 사용하려면 플러그인이 현재 플랫폼에 연결, 활성화 및 호환되어야 합니다. Herdr 관리 터미널 패널로 매니페스트에서 선언된 [[panes]] 명령을 시작합니다. 매니페스트 기본값은 overlay이며, 이는 활성 패널 위에 임시로 확대된 오버레이를 엽니다. 분할, 새 탭, 확대된 패널 또는 탭 레이아웃을 변경하지 않는 세션 모달 popup로 열 수도 있습니다. --width 및 --height는 80%과 같은 터미널 셀 또는 백분율의 외부 팝업 크기를 설정합니다. 생략된 치수는 기본적으로 터미널 크기의 절반으로 설정되며 팝업 최소값보다 작은 값은 고정됩니다. 팝업은 Herdr 패널이 아니며 HERDR_PANE_ID을 내보내지 않으며 패널 또는 에이전트 API에 참여하지 않습니다. 기본 비터미널 플러그인 패널은 플러그인 v1 외부에 있습니다.

새 패널은 TERM_PROGRAM=herdr로 식별되며 TERM_PROGRAM_VERSION은 Herdr의 버전으로 설정됩니다. 그들은 TERM=xterm-256color 및 COLORTERM=truecolor을 유지합니다. Herdr는 명시적인 시작 환경 값을 적용하기 전에 상속된 외부 터미널 세션 마커(iTerm2, WezTerm, Kitty, Windows Terminal, tmux, screen 및 Zellij), iTerm2의 LC_TERMINAL ID 및 알려진 Claude Code, Codex 및 OMP 세션 마커를 제거합니다. 이렇게 하면 새 패널이 원래 서버를 시작한 터미널이나 에이전트 세션을 요청하는 것을 방지할 수 있습니다. API 키 및 디스플레이 설정을 포함한 일반 환경 변수는 연결 클라이언트 환경으로 대체되지 않고 상속된 상태로 유지됩니다. SSH 에이전트 전달에는 자체 재연결 처리 기능이 있습니다. 이 정리로 인해 기존 패널 프로세스는 변경되지 않습니다.

--env KEY=VALUE은 프로세스 시작 명령에서 반복될 수 있습니다. 새로 시작된 프로세스에만 적용됩니다. HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ENV, HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_PANE_ID, HERDR_PLUGIN_ID, HERDR_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR, HERDR_PLUGIN_STATE_DIR, HERDR_PLUGIN_ENTRYPOINT_ID 및 HERDR_PLUGIN_CONTEXT_JSON와 같은 Herdr 관리 변수는 호출자가 제공한 환경과 충돌할 때 권한을 유지합니다.

이러한 의미는 읽기에 적용됩니다. pane wait-output의 경우에만 recent 및 recent-unwrapped 모두 래핑되지 않은 최근 스냅샷을 검색합니다. recent은 기본 철자로 유지됩니다.