CLI

현재 Deplite CLI는 사실상 Agent 바이너리 한 개예요.
관리·트리거 호출은 모두 HTTP API(API 레퍼런스)로 진행해주세요.

명령

명령	설명
`deplite-agent install`	1회용 설치 코드로 새 Agent 등록
`deplite-agent start`	등록된 자격으로 데몬 실행 (SSE 연결·heartbeat·워크플로우 감시·Job 실행)
`deplite-agent version` (`-v`, `--version`)	버전 출력
`deplite-agent help` (`-h`, `--help`)	도움말

install 플래그


deplite-agent install [--code <코드>] [--base-url <url>] [--data-dir <경로>] [--name <표시명>]

플래그	환경변수	기본값	설명
`--code`	`DEPLITE_INSTALL_CODE`	(없음, 필수)	대시보드에서 발급한 1회용 설치 코드
`--base-url`	`DEPLITE_BASE_URL`	`https://api.deplite.io/v1`	백엔드 베이스 URL
`--data-dir`	`DEPLITE_DATA_DIR`	OS별 사용자 설정 디렉토리(`os.UserConfigDir()/deplite-agent`)	자격 파일이 저장될 위치
`--name`		(호스트네임)	대시보드에서 보일 표시명

성공하면 데이터 디렉토리에 identity.json과 agent.key가 만들어져요.

start 플래그


deplite-agent start [--data-dir <경로>] [--workflows-dir <경로>] [--heartbeat <duration>]

플래그	환경변수	기본값	설명
`--data-dir`	`DEPLITE_DATA_DIR`	install과 동일	자격 파일 위치
`--workflows-dir`	`DEPLITE_WORKFLOWS_DIR`	`<data-dir>/workflows`	YAML 워크플로우 디렉토리
`--heartbeat`		`30s`	heartbeat 송신 주기

워크플로우 실행 시 자동 주입 환경변수

step의 run 명령이 실행될 때 다음이 환경에 들어와요. 자세한 우선순위는 워크플로우 문서에서 다뤄요.

변수	의미
`DEPLITE_PARAM_<KEY>`	트리거 `params`에서 자동 주입
`DEPLITE_SECRET_<KEY>`	워크플로우 `secrets`에 선언된 시크릿. Agent 환경변수 `DEPLITE_SECRET_<KEY>`에서 가져옴
`DEPLITE_WORKDIR`	이 step의 임시 작업 디렉토리
`TMPDIR`, `TMP`	`DEPLITE_WORKDIR`과 같은 값

Agent가 step 실행에 쓰는 셸은 DEPLITE_SHELL 환경변수로 오버라이드할 수 있어요.
step을 호스트에서 실행할지 컨테이너 안에서 실행할지는 Agent가 자동으로 감지하고, DEPLITE_HOST_EXEC로 직접 지정할 수 있어요(스텝 실행 환경 참고).

종료 코드

코드	의미
0	정상 종료 (signal 수신, revoke 등)
1	실행 실패 (자격·디렉토리·네트워크 등)
2	사용법 오류 (잘못된 플래그·필수 인자 누락)

시그널

SIGINT / SIGTERM — 진행 중인 작업을 정리한 뒤 graceful shutdown

로그

Agent는 stdout으로 구조화 로그(slog)를 그대로 흘려요.
운영체제 로그 시스템에 위임하는 게 표준 패턴이에요.


# systemd 환경
sudo journalctl -u deplite-agent -f

Job 단위 로그는 디스크에 따로 쌓지 않고 곧바로 서버로 스트리밍돼서, 대시보드 Jobs 화면에서 바로 확인할 수 있어요.

실전 예시

첫 등록과 일상 실행


# 1) 등록
deplite-agent install \
  --code "<1회용_설치_코드>" \
  --name "prod-server-01"
 
# 2) 데몬 실행
deplite-agent start

--data-dir을 명시하지 않으면 OS별 사용자 설정 디렉토리(os.UserConfigDir()/deplite-agent)가 자동으로 사용돼요.

Docker 한 줄 실행


docker run -d --name deplite-agent \
  --pid host \
  --privileged \
  -e DEPLITE_INSTALL_CODE="<1회용_설치_코드>" \
  -e DEPLITE_SECRET_DATABASE_URL="postgres://..." \
  -v deplite-credentials:/credentials \
  -v $(pwd)/workflows:/workflows:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DEPLITE_DATA_DIR=/credentials \
  -e DEPLITE_WORKFLOWS_DIR=/workflows \
  --restart unless-stopped \
  ghcr.io/deplite/agent:<version>

이미지는 GitHub Container Registry에만 배포돼요.
태그는 0.1.0처럼 v 접두사 없는 버전, 0.1 같은 major.minor, 그리고 latest(프리릴리스 제외)를 쓸 수 있어요.

--pid host와 --privileged를 함께 주면 step이 컨테이너 안이 아니라 호스트에서 실행돼요.
step이 docker·ssh 같은 호스트 도구를 호출한다면 이 구성이 권장돼요.
둘 중 하나라도 빠지면 컨테이너 실행 모드로 내려가니, 자세한 조건은 스텝 실행 환경에서 확인해주세요.

systemd 상태·로그 확인


sudo systemctl status deplite-agent
sudo journalctl -u deplite-agent -f --since "10 min ago"

워크플로우 디렉토리에 파일을 추가·수정·삭제하면 Agent가 fsnotify로 즉시 감지해요. 별도 신호 없이도 반영돼요.

CLI

명령