just로 프로젝트 명령을 한 파일에 정리하기

just는 프로젝트에서 반복하는 명령을 justfile에 이름 붙여 저장하는 명령 실행기입니다. 빌드 시스템을 새로 만드는 도구라기보다, README와 셸 기록에 흩어진 설치·검사·테스트·배포 명령을 팀이 같은 방식으로 실행하게 해줍니다. 이 글에서는 설치부터 인자가 있는 레시피, 환경 변수, 의존 관계, CI 적용과 제거까지 하나의 예제로 연결합니다.

언제 쓰나

프로젝트를 시작할 때마다 npm run lint, pytest, Docker 명령과 배포 스크립트의 긴 옵션을 기억해야 한다면 실행 방법이 사람의 기억에 묶여 있습니다. just는 이런 명령을 짧은 레시피 이름으로 공개합니다. make와 문법이 비슷하지만 파일 생성 시각을 비교하는 빌드 시스템이 아니라 명령 실행에 초점을 둡니다.

다음 경우에 특히 잘 맞습니다.

• 언어가 다른 도구를 한 프로젝트에서 함께 실행할 때
• 로컬과 CI가 같은 명령 진입점을 써야 할 때
• 새 팀원이 실행 순서와 필수 인자를 바로 확인해야 할 때
• 긴 Docker·클라우드 명령을 검토 가능한 파일로 관리할 때

반대로 언어별 패키지 스크립트만으로 충분하거나, 산출물 의존성과 증분 빌드가 핵심이라면 기존 빌드 도구를 유지하는 편이 낫습니다.

설치와 확인

macOS에서는 Homebrew가 가장 간단합니다. Linux와 Windows도 공식 패키지 목록과 사전 빌드 바이너리를 제공합니다.

brew install just
just --version

공식 설치 스크립트를 쓸 경우 원격 스크립트를 먼저 검토하고 설치 위치를 명시하세요. 최신 버전을 자동 조회하는 과정은 GitHub API 제한에 걸릴 수 있으므로 CI에서는 릴리스 태그를 고정하는 편이 재현성이 좋습니다.

mkdir -p "$HOME/bin"
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh \
  | bash -s -- --to "$HOME/bin" --tag 1.58.0
"$HOME/bin/just" --version

이 글의 버전 번호는 2026년 9월 18일 공식 릴리스 기준입니다. 다른 버전을 선택했다면 태그와 체크섬을 함께 확인하세요. just --version이 선택한 버전을 출력하면 설치가 끝난 것입니다.

첫 레시피

프로젝트 루트에 justfile을 만들고 다음 내용을 저장합니다.

# 사용 가능한 명령 표시
default:
  @just --list

# 개발 환경 준비
setup:
  npm ci

# 정적 검사
lint:
  npm run lint

# 테스트 실행
test:
  npm test

그다음 목록과 개별 레시피를 실행합니다.

just
just setup
just lint
just test

just는 현재 디렉터리와 상위 디렉터리에서 justfile을 찾습니다. 하위 폴더에서도 프로젝트 루트의 레시피를 실행할 수 있습니다. 기본적으로 각 명령을 실행 전에 표시하며, 줄 앞에 @를 붙이면 해당 명령 자체는 숨깁니다. 레시피의 명령 하나가 실패하면 그 레시피도 실패하므로 CI의 종료 코드로 사용할 수 있습니다.

인자와 기본값

환경 이름이나 포트를 레시피 인자로 받으면 긴 옵션을 복사할 필요가 없습니다.

# 로컬 서버 실행
serve host="127.0.0.1" port="3000":
  npm run dev -- --host {{host}} --port {{port}}

# 선택한 환경에 배포
deploy environment:
  ./scripts/deploy.sh "{{environment}}"

실행 예시는 다음과 같습니다.

just serve
just serve 0.0.0.0 4173
just deploy staging

{{host}}와 {{port}}는 셸에서 해석되기 전에 just가 치환합니다. 외부 입력을 그대로 명령 문자열에 끼우면 셸 해석 위험이 생길 수 있으므로, 공개 자동화에서는 허용 값 검증을 배포 스크립트 안에도 둡니다. 실제 비밀값은 인자로 넘겨 셸 기록에 남기지 말고 CI 비밀 저장소나 제한된 환경 변수를 사용하세요.

의존 관계

검사와 테스트가 모두 통과해야 패키지를 만들도록 연결할 수 있습니다.

check: lint test

build: check
  npm run build

ci: setup check build

just --dry-run ci
just ci

--dry-run은 실행할 명령을 먼저 보여줍니다. 배포·삭제처럼 영향이 큰 레시피는 실제 실행 전에 이 결과를 검토하세요. 의존 레시피는 각 레시피의 규칙에 따라 실행되므로 반드시 한 셸 세션의 상태를 공유한다고 가정하면 안 됩니다. 작업 디렉터리 변경이나 임시 환경은 필요한 명령과 같은 레시피 안에서 명시하는 편이 안전합니다.

환경 변수

프로젝트에 .env가 있다면 다음 설정으로 불러올 수 있습니다.

set dotenv-load

show-environment:
  @echo "NODE_ENV=${NODE_ENV:-unset}"

printf 'NODE_ENV=development\n' > .env
just show-environment

development가 출력되면 로딩이 정상입니다. .env에는 비밀이 들어갈 수 있으므로 저장소에 커밋하지 말고 .gitignore와 예제 파일을 분리하세요. CI에서는 플랫폼의 비밀 변수를 우선하고, justfile에 토큰이나 암호를 직접 기록하지 않습니다.

셸과 플랫폼

기본 Unix 환경에서는 sh가 필요합니다. Bash 전용 문법을 사용한다면 셸을 명시해 팀 환경의 차이를 줄일 수 있습니다.

set shell := ["bash", "-uc"]

shell-check:
  echo "Bash: $BASH_VERSION"

Windows와 Unix를 함께 지원한다면 한 레시피에 플랫폼별 문법을 뒤섞기보다 운영체제 전용 레시피 또는 Python·Node 스크립트로 복잡한 로직을 옮기는 편이 유지보수에 유리합니다. just는 실행 진입점을 통일하지만 각 명령이 요구하는 런타임까지 자동 설치하지는 않습니다.

CI에서 사용

CI에서는 just 버전을 고정하고 사람이 쓰는 것과 같은 레시피를 호출합니다.

steps:
  - uses: actions/checkout@v4
  - name: Install just
    uses: taiki-e/install-action@just
    with:
      version: 1.58.0
  - name: Run project checks
    run: just ci

서드파티 액션을 조직 정책상 허용하지 않는다면 공식 릴리스 바이너리와 SHA-256 파일을 검증해 설치하세요. just ci가 로컬에서도 성공하고 CI에서도 같은 종료 코드를 내는지 확인하는 것이 핵심입니다. CI 전용 옵션이 필요하면 숨기지 말고 ci 레시피에서 명시합니다.

목록과 진단

레시피가 예상대로 발견되는지 다음 명령으로 확인할 수 있습니다.

just --list
just --show ci
just --summary
just --dry-run ci
just --dump

• --list: 설명과 함께 실행 가능한 레시피를 보여줍니다.
• --show: 한 레시피의 정의를 확인합니다.
• --summary: 레시피 이름을 간단히 나열합니다.
• --dry-run: 실행될 명령을 미리 봅니다.
• --dump: 해석된 justfile을 출력해 디버깅에 씁니다.

레시피 위의 문서 주석은 목록에서 사용법을 설명하는 데 유용합니다. 팀이 자주 쓰는 레시피에는 목적과 위험 범위를 짧게 적어두세요.

흔한 오류

• No justfile found: 프로젝트 루트 또는 상위 경로에 justfile이 있는지 확인하고 just --list를 루트에서 실행합니다.
• Unknown recipe: just --summary로 실제 이름을 확인합니다. 별칭과 모듈을 썼다면 현재 버전의 매뉴얼도 확인합니다.
• 명령을 찾지 못함: just가 런타임을 설치하지는 않습니다. node --version, python --version처럼 레시피가 호출하는 도구부터 확인합니다.
• 셸 문법 오류: 기본 sh에서 Bash 전용 문법을 썼는지 확인하거나 set shell을 명시합니다.
• .env가 안 읽힘: set dotenv-load 위치와 실행 디렉터리, 실제 파일명을 확인합니다.
• CI에서만 실패: CI의 작업 디렉터리, PATH, 설치 버전과 비밀 변수 이름을 로컬 환경과 비교합니다.

제거와 복구

프로젝트에서 도입을 되돌릴 때는 먼저 CI와 문서가 just에 의존하지 않도록 원래 명령으로 복원합니다. 그다음 justfile을 제거하거나 보관 브랜치로 옮깁니다.

git grep -nE '\bjust( |$)'
brew uninstall just

공식 스크립트로 ~/bin/just에 설치했다면 해당 바이너리만 제거하되, 삭제 전에 command -v just로 정확한 위치를 확인하세요. justfile은 일반 텍스트이므로 레시피 안의 원래 명령을 README나 패키지 스크립트로 옮겨두면 복구가 쉽습니다.

이 글의 명령은 공식 매뉴얼과 1.58.0 릴리스 자료를 기준으로 작성했으며, 이 환경에서 프로젝트 전체를 직접 실행해 검증하지 않았습니다.

출처

• Just 공식 매뉴얼
• Quick Start
• 사전 빌드 설치
• 명령줄 옵션
• casey/just 릴리스