Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
cipi-cli는 Cipi 환경을 위한 명령줄 인터페이스(CLI)로, 서버, 애플리케이션, 데이터베이스, SSL 인증서 등 다양한 인프라 요소를 통합 관리할 수 있게 합니다. 사용자는 '프로필(profile)' 개념을 통해 여러 개의 독립된 서버를 구분하여 관리하며, 이를 통해 배포 및 상태 확인 등의 작업을 수행합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Cipi를 위한 명령줄 인터페이스(Command-line interface)입니다. 터미널에서 서버, 애플리케이션, 데이터베이스, SSL 인증서, 배포, PHP, 서비스, SMTP, 상태 확인(healthchecks), 디스크 사용량 및 앱의 cipi.yml을 관리할 수 있습니다.
git clone https://github.com/cipi-sh/cli.git
cd cli
make build
...
릴리스(Releases) 페이지에서 사용자의 플랫폼에 맞는 최신 릴리스를 다운로드한 후 다음 명령어를 실행합니다:
chmod +x cipi-cli-*
sudo mv cipi-cli-* /usr/local/bin/cipi-cli
**프로필(profile)**은 Cipi 서버에 대한 이름이 지정된 연결(API 엔드포인트 + 토큰)입니다. 보유한 서버 수만큼 많은 프로필을 사용할 수 있습니다. servers라는 별칭(alias)은 profiles와 동일하게 작동합니다.
cipi-cli prod apps list # 명시적 프로필 사용
cipi-cli apps list # 기본 프로필 사용
먼저 Cipi 호스트에서 토큰을 생성한 후(cipi api token create), 로컬에 프로필 이름으로 저장합니다:
cipi-cli api token add prod
cipi-cli api token add staging
# 또는: cipi-cli configure --profile prod
...
다음 항목을 입력하라는 메시지가 표시됩니다:
prod, staging) (생략 시)https://api.example.com)자격 증명은 ~/.cipi/config.json에 프로필별로 저장됩니다 (권한 0600). 프로필 이름을 생략한다고 해서 자동으로 default에 기록되는 것은 아니므로, 요청을 받게 됩니다.
비대화형(Non-interactive) 방식:
cipi-cli api token add prod --endpoint https://api.example.com --token "1|yourtoken..."
cipi-cli profiles add staging --endpoint https://staging.example.com --token "1|yourtoken..."
cipi-cli profiles # 서버 목록 표시 (별칭: cipi-cli servers)
cipi-cli profiles show prod # 특정 서버 검사
cipi-cli profiles use prod # 기본 서버 설정
...
프로필을 삭제하는 것은 로컬 자격 증명만 제거하며, 원격 서버에는 아무런 변경 사항이 없습니다.
특정 서버를 대상으로 하려면 모든 명령어 앞에 프로필 이름을 접두사로 붙이세요:
cipi-cli prod apps list
cipi-cli staging apps show myapp
cipi-cli prod deploy myapp
...
cipi-cli profiles use prod를 실행한 후에는 접두사를 생략할 수 있습니다:
cipi-cli apps list # 기본 프로필(prod) 사용
모든 명령어는 상세 도움말을 제공합니다:
cipi-cli --help
cipi-cli profiles --help
cipi-cli apps --help
...
cipi-cli apps list 모든 애플리케이션 목록 표시 (ENV 열: 환경 레이블)
cipi-cli apps show <name> 애플리케이션 상세 정보 표시
cipi-cli apps create [flags] 새로운 애플리케이션 생성
...
별칭(Alias): app → apps.
생성 플래그(Create flags): --user, --domain, --php, --repository, --branch, --custom, --docroot, --engine, --octane, --node, --framework, --node-version, --build, --start, --output, --health-path (Node 앱은 --php를 사용하지 않음), --node-build (Laravel 앱 전용: 배포 전에 실행되는 에셋 빌드 과정. 예: --node-build "npm ci && npm run build"; 반드시 npm/npx/yarn/pnpm/bun/node로 시작해야 하며, &&와 ; 사용 가능, 파이프/리디렉션/백틱/$( ) 불가, 최대 200자; Cipi 5.6.0+ / API 1.34+ 필요). 대화형 플로우는 Laravel 앱의 선택적 빌드 명령어 프롬프트를 제공합니다.
환경(Environments): --env는 앱의 환경을 지정하는 레이블입니다. 허용되는 값은 production(기본값), staging, 또는 1~32자 길이의 소문자 영문, 숫자, -, 또는 _로 구성된 임의의 레이블입니다. (apps create --env staging, apps edit <이름> --env staging; CLI는 서버 호출 전에 다른 값을 거부합니다). apps list에서는 이 정보를 ENV 열에 표시하며, apps show에서는 환경(Environment)으로 표시됩니다 (서버가 아무것도 보내지 않으면 production). 또한 이 레이블은 yml 명령어가 읽는 파일을 결정하는데, 먼저 cipi-<env>.yml을 시도하고 그 다음 cipi.yml을 시도합니다. Cipi 5.8.0+ / API 1.36+가 필요하며; 이전 버전의 서버는 이 필드를 누락시키므로, create/edit 후 CLI가 앱을 다시 읽어 레이블이 유지되지 않았음을 경고합니다.
create 작업이 완료되면 CLI는 앱 자격 증명(SSH, 데이터베이스), 배포 키(deploy key), 웹훅(webhook) 및 빌드 정보를 출력합니다. Cipi 5.6.0+ / API 1.34+를 사용하면 apps create와 apps edit --repository/--branch는 배포 키가 해당 저장소에 접근할 수 있는지 여부도 보고합니다: 접근 가능(브랜치 포함), 접근 가능하지만 브랜치가 누락됨, 또는 읽기 불가(첫 번째 배포에서 실패하며; Git의 오류 메시지와 서버에서 실행해야 할 수정 명령이 표시됩니다). 이전 버전의 서버는 아무것도 보고하지 않습니다. --json을 사용하면 작업 결과가 {"data": …} 형식으로 출력되며, 여기에 repository_access와 build 정보가 포함됩니다.
편집 플래그(Edit flags): --php, --repository, --branch, --domain (기본 도메인 이름 변경; Cipi 4.6.2+ / API 1.9.0+ 필요), --env (환경 레이블; Cipi 5.8.0+ / API 1.36+ 필요)와 위에서 언급된 Node 플래그들이 있습니다.
로그 플래그(Logs flags): --type(기본값 all: nginx, php, worker, deploy, laravel), --page(기본값 1 = 가장 최신), --per-page(기본값 50, 최대 1000; API 1.11.9+ 필요)
cipi-cli domains 모든 앱에 걸친 모든 도메인과 별칭을 나열합니다
별칭: domain → domains.
단일 앱의 별칭 관리는 아래 별칭(Aliases) 섹션을 참조하십시오.
cipi-cli deploy <app> 배포 트리거
cipi-cli deploy rollback <app> [-y] 이전 릴리스로 롤백
cipi-cli deploy unlock <app> 멈춘 배포 잠금 해제
...
cipi-cli yml <app> 앱의 cipi.yml을 적용할 때 변경될 내용
cipi-cli yml plan <app> 동일함 (별칭: show, status, diff)
cipi-cli yml apply <app> [-y] 적용 (비동기 작업(async job): -y가 아닌 경우 미리보기 + 확인 필요)
...
앱이 레포지토리에 포함하는 cipi.yml은 해당 앱이 예상하는 서버 상태(별칭, www 리디렉션, 기본 인증, 리디렉션, 프록시, PHP 버전 및 설정, 제한 사항, 추가 데이터베이스, 워커, 헬스 체크, 배포 옵션, 크론 작업, 백업, 배포 후 단계)를 설명합니다. 이러한 명령어들은 호스트의 cipi yml을 미러링하며 라이브 릴리스의 파일을 읽으므로, 먼저 커밋하고 배포해야 합니다. 환경 레이블이 있는 앱(apps create --env staging)은 먼저 cipi-<env>.yml을 읽고 공유된 cipi.yml로 폴백(fallback)합니다. 따라서 하나의 레포지토리가 환경별 파일(Cipi 5.8.0+ / API 1.36+)을 포함할 수 있습니다. 파일 내의 deploy.branch는 앱이 배포되는 git 브랜치입니다.
yml plan은 환경 레이블과 사용 중인 파일을 출력하며 (비(非)운영 환경 앱이 공유된 cipi.yml에 있을 경우 알림), 자동 적용 여부, 유효성 검사 오류 및 경고, 변경 사항, 차단 요소(차단 요소가 목록화되는 동안에는 변경 사항을 적용하지 않습니다) 그리고 다음 배포 후 발생할 상황을 보여줍니다. 파일이 없거나, 유효하지 않거나, 적용을 방해하는 무언가가 있을 경우 종료 코드 1을 반환합니다 (--json은 데이터를 출력하고 종료 코드 0을 반환합니다). yml apply는 계획(plan)을 미리 보고하며 app-yml-apply 작업을 전송하기 전에 사용자에게 확인을 요청합니다 (-y는 둘 다 건너뜁니다). 그런 다음 적용됨, 변경 없음, 부분적 (실패한 변경 사항 포함), 차단됨, 유효하지 않음 또는 파일 없음 중 하나의 결과를 출력하며, 적용되거나 변경되지 않은 경우가 아니면 종료 코드 1을 반환합니다. --json은 작업 결과를 {"data": …} 형식으로 출력합니다. yml auto <app> on은 CLI, 패널(panel), Git 웹훅 배포를 모두 포괄합니다. 따라서 저장소에 커밋할 수 있는 모든 사용자는 앱의 별칭, PHP 설정, 제한 사항, 워커, 배포 브랜치 및 레시피, 예약된 명령어, 데이터베이스 및 백업 일정을 변경할 수 있습니다 (Node 앱의 경우 모드, Node 버전, 빌드 및 시작 명령도 포함됩니다). 따라서 CLI는 이를 알리고 -y가 전달되지 않는 한 확인을 요청합니다.
Cipi 5.6.4 이상, API 1.35 이상 및 yml-view (plan, auto status) / yml-manage (apply, auto on|off) 토큰 기능이 필요합니다. 기존 토큰에는 해당 기능이 포함되어 있지 않으므로, 다음 명령어로 토큰을 생성해야 합니다 (cipi api token create). Cipi 5.6.4는 자동 적용(auto-apply)이 활성화된 경우 Git 웹훅 배포 시 cipi.yml을 적용하는 릴리스이기도 합니다.
cipi-cli ssl install <app> Let's Encrypt 인증서 설치
cipi-cli ssl force <app> HTTP → HTTPS 리디렉션 재적용 (4.8+)
cipi-cli www status <app> www/apex 리디렉션 상태 표시
cipi-cli www add <app> www/apex 대응 별칭 추가
cipi-cli www force-to-root <app> 301 리디렉션 www → apex
...
cipi-cli redirect list <앱> 전체 앱 및 경로 리다이렉트 목록 보기 (5.4.1+)
cipi-cli redirect set|unset|enable|disable <앱>
cipi-cli redirect add|remove <앱> 경로 리다이렉트 추가/제거 (--from, --to)
...
별칭(Alias): redirects → redirect, proxy → proxies.
앱 도메인(및 별칭)의 DNS는 이미 서버를 가리켜야 합니다.
cipi-cli aliases list <앱> 별칭 목록 보기
cipi-cli aliases add <앱> <도메인> 별칭 추가
cipi-cli aliases remove <앱> <도메인> [-y] 별칭 제거
별칭(Alias): alias → aliases.
cipi-cli db engines DB 엔진 목록 및 기본값 보기 (4.8+)
cipi-cli db install <엔진> 엔진 설치: mariadb|pgsql (5.0.6+)
cipi-cli db list 모든 데이터베이스 목록 보기
...
별칭(Aliases): database, dbs → db.
API 1.19 이상 버전에서는 데이터베이스 삭제 및 기본 엔진 설정 기능이 제거되었으므로, 호스트에서 cipi db delete / cipi db default를 사용해야 합니다.
db anonymize는 Cipi API가 아닌 Laravel 앱에 설치된 cipi/agent 패키지와 통신합니다: 이 명령어는 앱의 .env 파일에서 앱 URL (APP_URL, 아니면 https://<주요 도메인>) 및 CIPI_ANONYMIZER_TOKEN을 읽어와 API를 통해 가져온 후, 앱에 대해 POST /<CIPI_ROUTE_PREFIX>/db를 호출합니다. 에이전트는 앱 큐에서 작업을 실행하고 유효 기간 15분 동안 서명된 다운로드 링크를 이메일로 전송합니다.
# 앱에서의 일회성 설정
cipi-cli apps artisan myapp cipi:service anonymize --enable
cipi-cli apps artisan myapp cipi:generate-token anonymize
...
익명화 플래그 (Anonymize flags): --email / -e (생략 시 프롬프트 요청), --url (앱 기본 URL 재정의, 예: 앱이 www로 리다이렉트하는 경우), --token (베어러 토큰 재정의)
다운로드 플래그 (Download flags): --output / -o (-은 stdout용), --force / -f (덮어쓰기)
cipi-cli php list 설치된 버전, FPM 상태, 기본 설정 (5.0.6+)
cipi-cli php install <version> PHP 8.3 / 8.4 / 8.5 설치
기본 PHP 버전 전환 및 버전 제거는 호스트 전용(cipi php switch|remove)입니다.
cipi-cli services list [name] 시스템 서비스 및 상태 (5.0.6+)
cipi-cli services restart <name> 서비스 재시작 (nginx, mariadb, …)
cipi-cli ssh-keys list cipi 사용자의 인증 키 (5.0.6+)
...
별칭(Aliases): service → services, ssh → ssh-keys.
cipi-cli smtp show 현재 SMTP 설정 (비밀번호는 표시되지 않음, 5.0.7+)
cipi-cli smtp set [flags] 설정; 누락된 플래그는 현재 값을 유지합니다.
cipi-cli smtp test 테스트 이메일 전송
...
설정 플래그: --host, --port (587), --user, --password (최초에 필요), --from, --to, --tls (기본값 활성화), --enabled (기본값 활성화), --no-test
cipi-cli health list 구성된 모든 앱의 상태 확인 기능 (5.0.7+)
cipi-cli health show <app> 특정 앱의 상태 확인 및 상태 정보
cipi-cli health set <app> [--url] [--expect] 활성화/업데이트 (기본값 https://<domain>/up, 200)
...
cipi-cli status 전역 개요 — 서버당 한 줄씩 표시
cipi-cli status <profile> 단일 서버의 전체 상세 정보
cipi-cli <profile> status 프로필 접두사를 통한 동일한 기능
글로벌 컬럼: NAME, IP, CPU, RAM, HDD, APPS, SVC, CIPI.
API 토큰 능력 status-view (GET /api/status, 호스트의 cipi status와 동일한 데이터)이 필요합니다.
cipi-cli disk 디스크 사용량: 서버 파일 시스템, 그리고 모든 앱 (GB 및 %)
cipi-cli disk db 엔진별 모든 데이터베이스 크기 (MB)