Failproof AI CLI

npm install -g failproofai로 로컬 CLI를 설치하세요. 인수 없이 실행하면 로컬 정책 대시보드가 열립니다. 이 패키지는 Node.js 20.9 이상이 필요합니다. Bun 1.3 이상은 개발 및 소스 설치에서 지원됩니다. failproofai configure와 failproofai setup은 failproofai config의 별칭입니다. failproofai policy, failproofai pack, failproofai p는 모두 failproofai policies의 다른 표기법입니다 — 팩과 단일 정책은 한 개념에 대한 세 가지 명령이었으나 이제 하나로 통합되었습니다. 기존 표기법은 두 가지 예외를 제외하고 계속 작동합니다: pack list <source>는 이제 policies show <source>이고, pack build는 이제 publish입니다.

머신 설정

CLI를 설치한 후 머신 키를 셸로 읽어옵니다. read -s는 에코되지 않는 프롬프트에서 입력을 받으므로 명령어에 키가 노출되지 않습니다:

npm install -g failproofai
read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

그런 다음 머신을 설정하고 적용할 정책을 선택합니다:

failproofai config
failproofai policies add FailproofAI/policies
failproofai config --status

failproofai config는 설정의 전 과정을 담당합니다: failproofaid 서비스를 설치하고(루트 권한으로 한 번, sudo -n 사용 — 대화형 비밀번호 프롬프트 없음), 발견된 모든 에이전트 CLI에 훅을 연결하며, 키가 있으면 Cloud에 연결합니다. 터미널이 없는 환경(CI, 컨테이너, 에이전트가 구동하는 경우)에서는 묻지 않고 적용하며, 요청한 작업 중 하나라도 완료되지 않으면 종료 코드 1을 반환합니다. 이 명령은 정책을 선택하지 않습니다. 그것은 두 번째 명령의 역할이며, 이 단계 없이 새로 설정된 머신은 항상 활성화된 가드 외에는 아무것도 적용하지 않습니다. --token 대신 환경 변수를 사용하는 것을 권장합니다: 명령줄 인수는 시스템의 모든 사용자가 ps로 읽을 수 있기 때문입니다. 환경 변수가 보호하는 것은 그것뿐입니다 — export를 포함하여 어떤 명령어에 키를 직접 입력하면 여전히 셸 히스토리에 남기 때문에, 위에서 read -s를 사용해 읽어오는 것입니다. CI에서는 시크릿 스토어에서 설정하고 셸 트레이싱(set -x)을 끄거나, 트레이스가 키를 출력할 수 있습니다.

--connect <url>은 이미 설정된 머신을 등록합니다. 등록이 완료되는 즉시 반환합니다 — 데몬을 설치하거나 훅을 연결하지 않습니다. 아직 설정되지 않은 머신에서는 failproofai config(또는 failproofai config --token <key>)를 사용하세요. 그렇지 않으면 연결된 것으로 표시되지만 실제로는 아무것도 수집하거나 적용하지 않습니다.

인수 없이 failproofai를 실행하면 로컬 정책 대시보드가 열립니다.

명령어	결과
`failproofai config`	머신 설정: 에이전트, 데몬, 키가 있으면 Cloud 연결
`failproofai config --token <key>`	아무것도 묻지 않고 한 번에 설정 및 연결
`failproofai config --connect <url>`	이미 설정된 머신 등록 — 데몬 및 훅 없음
`failproofai config --status`	연결, 데몬, 전달, 일시 중지 상태 표시
`failproofai policies`	빌트인, 커스텀, 컨벤션, 팩, Cloud 관리 정책 목록
`failproofai policies --install`	에이전트 CLI에 훅 연결. 자체적으로는 정책을 활성화하지 않음
`failproofai policies add <name>`	정책 하나 활성화 — 빌트인 또는 설치된 팩의 `<pack-id>:<name>`
`failproofai policies remove <name>`	정책 하나 비활성화, 동일한 명명 방식
`failproofai policies --uninstall`	정책 비활성화 또는 하네스 훅 제거
`failproofai policies show <owner>/<repo>`	팩이 포함하는 내용을 매니페스트에서 읽어 설치 전에 확인
`failproofai policies show <owner>/<repo> --releases`	게시된 모든 버전과 현재 설치된 버전
`failproofai policies add <source>`	GitHub 릴리스에서 정책 팩 설치; 태그 없이 실행하면 최신 버전을 가져와 고정
`failproofai publish`	자신의 정책을 팩으로 배포; `--init`으로 시작 템플릿 생성
`failproofai policies remove <publisher/name>`	팩 제거
`failproofai audit`	로컬 에이전트 히스토리 스캔 및 로컬 감사 뷰 열기
`failproofai audit --schedule [days] --email <address>`	주기적인 로컬 스캔 예약 및 결과를 이메일로 전송
`failproofai audit --status`	보고서 주소, 간격, 다음 예약 스캔 표시
`failproofai audit --no-schedule`	감사 히스토리를 삭제하지 않고 주기적 스캔 중단
`failproofai harness list`	추가 캡처 경로 목록
`failproofai flush --wait`	현재 이벤트 스풀 전달
`failproofai backfill --since 30d`	이전에 통과된 히스토리 재읽기
`failproofai config --pause [duration]`	로컬 세션 하나를 기본 30분(최대 8시간) 동안 일시 중지
`failproofai config --resume`	일시 중지된 로컬 세션 하나 재개; `--all`로 모든 일시 중지 해제
`failproofai update`	패키지 마이그레이션 완료 및 데몬 업데이트
`failproofai migrate --dry-run`	대기 중인 홈 레이아웃 마이그레이션 미리 보기 또는 실행
`failproofai uninstall`	패키지 제거 전 훅 및 데몬 제거
`failproofai --version`	설치된 패키지 버전 출력
`failproofai --help`	명령어 및 전체 사용법 표시

설정 플래그

플래그	사용법
`--token <key>`	비대화형으로 설정 및 연결; `FAILPROOFAI_CLOUD_TOKEN`에서도 읽음
`--url <url>`	`app.befailproof.ai` 외 다른 곳에 연결; `FAILPROOFAI_CLOUD_URL`에서도 읽음
`--connect <url>`	이미 설정된 머신에서 등록만 수행. 데몬 및 모든 훅 건너뜀
`--machine-id <id>`	안정적인 머신 ID 설정
`--machine-label <name>`	이미 연결된 머신 이름 변경. 단독으로는 설정을 실행하지 않으므로, 설정 중이 아니라 `failproofai config` 이후에 사용
`--no-transcripts`	트랜스크립트 내용 없이 결정 사항 전송
`--disconnect`	Cloud 정책 풀 및 이벤트 전달 중단
`--status`	현재 머신 상태 표시
`--pause [duration]`	현재 디렉토리에서 가장 최근 세션 일시 중지; 초, 분, 시간 단위 허용, 기본값 30분
`--resume`	일치하는 일시 중지 조기 종료
`--session <id>`	일시 중지 또는 재개할 명시적 세션 지정
`--all`	`--resume`과 함께 사용 시 모든 활성 일시 중지 종료

로컬 일시 중지는 한 세션에 대해 빌트인, 커스텀, 컨벤션, 팩 정책을 중단합니다. 항상 만료되며 Cloud 관리 정책은 비활성화하지 않습니다. block-failproofai-commands — 항상 활성화되어 있으며 비활성화하거나 일시 중지할 수 없음 — 는 에이전트가 이 탈출 수단을 직접 사용하는 것을 방지합니다.

정책 플래그

플래그	사용법
`--install`, `-i`	하네스 훅 설치. 이후에 오는 이름은 해당 정책을 활성화하며, 없으면 정책 변경 없음
`--uninstall`, `-u`	정책 비활성화 또는 훅 제거
`--cli <names...>`	지원되는 하네스 하나 이상 지정
`--scope user\|project\|local\|all`	설정 범위 선택; `all`은 제거용
`--beta`	베타 정책 포함
`--custom`, `-c <path>`	커스텀 정책 파일 유효성 검사 및 로드; 반복 가능

전달 및 유지 관리 플래그

명령어	플래그
`backfill`	`--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run`
`flush`	`--wait`, `--timeout <seconds>`
`update`	`--no-daemon`
`migrate`	`--dry-run`
`uninstall`	`--purge`, `--dry-run`, `--yes`

failproofai update는 npm install -g failproofai@latest 이후에 실행해야 합니다; 홈 레이아웃 마이그레이션을 수행하고, 일치하는 데몬 바이너리를 설치하며, 서비스를 재시작합니다. --no-daemon은 레이아웃 마이그레이션만 수행합니다.

하네스 경로

failproofai harness list [harness]
failproofai harness add-path <harness> [label=]<path>
failproofai harness remove-path <harness> <path-or-label>

지원되는 하네스 이름은 claude, codex, copilot, cursor, opencode, pi, hermes, openclaw, factory, devin, antigravity, goose입니다. 레이블은 두 루트에 동일한 프로젝트 복사본이 있을 때 파생된 에이전트 ID의 네임스페이스를 구분합니다. 겹치는 루트와 중복 레이블은 중복 수집이나 커서 손상을 방지하기 위해 거부됩니다. 추가 경로 설정은 데몬 재시작 없이 다시 로드됩니다. 컨테이너 환경에서는 FAILPROOFAI_<HARNESS>_EXTRA_PATHS라는 이름의 쉼표로 구분된 변수로 파일에 설정된 추가 경로를 대체할 수 있습니다. 예를 들면:

export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b"

환경 변수

지속적인 머신 동작에는 설정 파일을 사용하세요. 환경 변수는 컨테이너, 테스트, 단일 프로세스에 가장 유용합니다.

변수	사용법
`FAILPROOFAI_CLOUD_TOKEN`	`--token` 대신 Cloud 키. 이 방법을 권장합니다: 인수는 모든 사용자가 `ps`로 읽을 수 있습니다. `read -s`나 CI 시크릿 스토어에서 설정하고, 절대로 명령어에 직접 입력하지 마세요 — 어떤 방식이든 셸 히스토리에 남습니다
`FAILPROOFAI_CLOUD_URL`	`--url` 대신 Cloud URL. 데몬이 읽는 동일한 변수
`FAILPROOFAI_HOME`	전체 `~/.failproofai` 레이아웃 재배치
`FAILPROOFAI_LOG_LEVEL`	로컬 로깅 상세도 설정
`FAILPROOFAI_HOOK_LOG_FILE`	선택한 파일에 훅 진단 기록
`FAILPROOFAI_TELEMETRY_DISABLED=1`	이 프로세스에 대한 익명 텔레메트리 비활성화
`FAILPROOFAI_NO_FIRST_RUN=1`	대화형 최초 실행 설정 건너뜀
`FAILPROOFAI_NO_AUTO_AUDIT=1`	설정 후 로컬 감사 건너뜀
`FAILPROOFAI_LLM_BASE_URL`	LLM 정책에서 사용하는 OpenAI 호환 엔드포인트 재정의
`FAILPROOFAI_LLM_API_KEY`	LLM 정책에서 사용하는 API 키 제공
`FAILPROOFAI_LLM_MODEL`	LLM 정책에서 사용할 모델 선택
`FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS`	커스텀 정책 모듈 로딩 시간 제한
`FAILPROOFAI_NO_DOWNLOAD=1`	팩 및 데몬 바이너리 가져오기 거부; 설치된 항목은 계속 적용됨
`FAILPROOFAI_PACK_BASE_URL`	`github.com` 대신 미러에서 팩 가져오기
`FAILPROOFAI_<HARNESS>_EXTRA_PATHS`	하나의 하네스에 대해 설정된 추가 캡처 경로 대체
`NO_COLOR`	색상 터미널 출력 비활성화

CLAUDE_PROJECTS_PATH, CURSOR_HOME, HERMES_HOME, OPENCLAW_HOME과 같은 에이전트별 홈 변수는 Failproof AI가 해당 하네스의 로컬 세션을 탐색하는 위치를 재정의합니다.

머신 안전하게 일시 중지 또는 제거

failproofai config --pause
failproofai config --status
failproofai config --resume

로컬 세션 일시 중지는 Cloud 관리 정책을 비활성화하지 않습니다. 롤아웃 자체가 문제인 경우 Cloud 적용 워크플로를 통해 Cloud 배포를 복원하세요. npm 패키지를 제거하기 전에 설치된 훅과 데몬을 먼저 제거하세요:

failproofai uninstall --dry-run
failproofai uninstall --yes
npm rm -g failproofai

버전별 세부 정보는 failproofai <command> --help를 실행하세요.

npm rm -g failproofai 전에 failproofai uninstall을 실행하세요; npm은 설치된 에이전트 훅이나 데몬 서비스를 제거하지 않습니다.

Connect your agents

Reference

머신 설정

설정 플래그

정책 플래그

전달 및 유지 관리 플래그

하네스 경로

환경 변수

머신 안전하게 일시 중지 또는 제거

​머신 설정

​설정 플래그

​정책 플래그

​전달 및 유지 관리 플래그

​하네스 경로

​환경 변수

​머신 안전하게 일시 중지 또는 제거

머신 설정

설정 플래그

정책 플래그

전달 및 유지 관리 플래그

하네스 경로

환경 변수

머신 안전하게 일시 중지 또는 제거