문서컨벤션레퍼런스Cheatsheet
문서컨벤션레퍼런스Cheatsheet
사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
CLI 레퍼런스▾
명령어WorkspaceApplicationLibraryModuleScalarPackagePagePrimitiveWorkflowQualityPipelineContextAgentGuideline
AkanJS 레퍼런스▾
akanjs/baseakanjs/commonakanjs/constantakanjs/fetchakanjs/signalakanjs/serverakanjs/clientakanjs/webkit
UI 레퍼런스▾
OverviewCoreDisplayFormsOverlaysSystemAgent커스터마이즈

클라우드 명령

Akan Cloud 로그인, 프레임워크 업데이트, env 값 옮기기, 파이프라인 시크릿 관리에 쓰는 명령 여덟 가지로, 필요할 때만 씁니다. 내부 배포용 명령은 일부러 이 페이지에서 뺐습니다.
이 페이지에서 쓰는 말
Akan Cloud
https://cloud.akanjs.com에서 계정, env 값, 터널을 관리하는 서비스입니다.
env 값
앱과 라이브러리마다 있는 env/env.client.<env>.ts, env/env.server.<env>.ts 파일로, git에 올리지 않습니다.
AKAN_WORKSPACE_ID
루트 .env에 적는 클라우드 워크스페이스 id로, env 값을 보관할 곳을 정합니다.
SCP 서버
클라우드 워크스페이스가 없을 때 env 값을 보관하는 자체 서버로, SSH로 접속합니다.
파이프라인 시크릿
빌드 step이 환경변수로 읽는 이름 붙은 값입니다. 쓰기만 하고 다시 읽을 수는 없습니다.
명령마다 접속하는 곳
명령
Akan Cloud
SCP
npm
이 컴퓨터만
계정
login
✓
브라우저로 로그인하고 세션을 저장합니다.
logout
✓
클라우드에 연락하지 않고 저장된 세션만 지웁니다.
프레임워크
update
✓
npm에서 설치하고, --registry local이면 로컬 레지스트리에서 설치합니다.
env 값
download-env
✓
✓
워크스페이스가 쓰는 쪽(Akan Cloud 또는 SCP 서버)에서 env 값을 내려받습니다.
upload-env
✓
✓
로컬 env 값을 같은 곳에 올려, 다음 download-env가 받게 합니다.
파이프라인 시크릿
upload-secret
✓
파이프라인 step이 읽을 이름 붙은 시크릿을 저장합니다.
list-secrets
✓
시크릿의 이름과 범위를 보여 주고, 값은 보여 주지 않습니다.
remove-secret
✓
프로젝트에서 시크릿을 지웁니다.
✓접속함접속 안 함
  • 워크스페이스 루트에서 실행합니다. 대부분의 akan 명령처럼 package.json, tsconfig.json, .env가 있는 폴더에서 실행해야 합니다.
  • --host로 다른 클라우드를 가리킵니다. Akan Cloud와 통신하는 명령은 모두 이 옵션을 받으므로, 직접 운영하는 클라우드도 같은 명령으로 씁니다. 루트 akan.config.ts의 cloud: { host }가 기본값을 정합니다.
  • 로그인은 컴퓨터마다, 호스트마다 하나입니다. 세션은 ~/.akan/config.json에 저장되므로 이 컴퓨터의 모든 워크스페이스가 함께 씁니다. --host와 cloud.host는 모두 끝의 슬래시를 뗀 URL의 origin과 경로로 읽으므로, 끝의 슬래시나 대문자 호스트, 기본 포트가 붙어도 같은 세션입니다.
  • 터미널이 없으면 빠진 인자는 오류입니다. CI처럼 stdin이 파이프로 이어졌거나 닫혀 있으면 빠진 인자나 옵션을 묻지 않고, 무엇이 빠졌는지 알리는 오류로 바로 멈춥니다. 실행 중에 묻는 질문(실행할 스크립트, 확인, 복사할 env 서버 등)도 같은 방식으로, 답이 되는 옵션을 알려 주며 멈춥니다.
env 값을 보관하는 곳
download-env와 upload-env는 루트 .env를 읽어 보관 위치를 정합니다. 둘은 같은 곳을 쓰므로, 올린 것을 그대로 내려받습니다.
보관처쓰는 경우
↳ 압축본이 있는 곳
Akan CloudAKAN_WORKSPACE_ID가 있을 때
그 id의 클라우드 워크스페이스이며, 필요하면 먼저 로그인합니다.
SCP 서버AKAN_WORKSPACE_ID가 비어 있을 때
목록에서 고른 서버의 ~/secrets/<repo>/env.tar입니다.
파이프라인 시크릿
  • 시크릿은 프로젝트에 속합니다. 루트 .env의 AKAN_WORKSPACE_ID가, --subspace를 주면 그 subspace의 workspaceId가 프로젝트를 정하고, akan login으로 로그인한 그 프로젝트 멤버만 바꾸거나 볼 수 있습니다.
  • step은 이름으로 시크릿을 요청합니다. secrets에 그 이름을 적은 step만, 같은 이름의 환경변수로 값을 받습니다.
관련 페이지
애플리케이션 환경설정→
이 명령들이 옮기는 env/ 파일에 무엇을 적는지 설명합니다.
secrets→
env 값과 함께 옮길 시크릿 파일을 선언합니다.
빌드 파이프라인→
파이프라인 step에 빌드 때 읽을 시크릿을 줍니다.
터널 명령→
akan login 세션으로 로컬 앱을 공개 URL에 공유합니다.

login

이 컴퓨터에서 Akan Cloud에 로그인합니다. CLI가 브라우저에 로그인 페이지를 열고, 그곳에서 로그인을 마칠 때까지 기다립니다.
형식
옵션
--hostString기본값 cloud.host, 없으면 Akan Cloud
사용할 클라우드입니다. 생략하면 루트 akan.config.ts의 cloud.host, 없으면 https://cloud.akanjs.com입니다(프레임워크 저장소(USE_AKANJS_PKGS=true)에서는 http://localhost:8283).
참고
브라우저
로그인 URL과 QR 코드를 출력하고 브라우저로 열며, 브라우저가 열리지 않으면 URL에 직접 접속합니다.
제한 시간
10분 안에 로그인하지 않으면 멈추므로, 다시 실행합니다.
이미 로그인됨
계정 닉네임을 출력하고, 브라우저를 열지 않은 채 끝납니다.
만료 임박 세션
만료가 가깝거나 지났으면 먼저 갱신하고, 갱신에 실패할 때만 브라우저를 엽니다.
저장 위치
~/.akan/config.json에 호스트마다 세션 하나를 저장하며, 본인만 읽을 수 있습니다.
쓰는 명령
akan tunnel과 akan start --share에 필요하며, env 명령은 필요하면 스스로 로그인합니다.
예시

logout

이 컴퓨터의 Akan Cloud 로그인을 해제합니다. 계정을 바꾸거나, 이 컴퓨터의 클라우드 접근을 없앨 때 씁니다.
형식
옵션
--hostString기본값 cloud.host, 없으면 Akan Cloud
사용할 클라우드입니다. 생략하면 루트 akan.config.ts의 cloud.host, 없으면 https://cloud.akanjs.com입니다(프레임워크 저장소(USE_AKANJS_PKGS=true)에서는 http://localhost:8283).
참고
지우는 것
그 --host에 저장된 세션만 지우고, 다른 호스트의 세션은 그대로 둡니다.
로그인 안 됨
세션이 없다고 알리고 아무것도 바꾸지 않습니다.
예시

update

전역 akan CLI와 이 워크스페이스의 Akan.js 패키지를 릴리스 태그의 최신 버전으로 올립니다. 보통은 latest를 쓰고, beta, rc, canary는 그 채널을 일부러 시험할 때만 씁니다.
형식
옵션
--tagString기본값 latestlatest | dev | canary | beta | rc | alpha
설치할 릴리스 채널입니다.
--registryString기본값 npmnpm | local
local은 AKAN_NPM_REGISTRY이고, 비어 있으면 http://127.0.0.1:4873입니다.
참고
package.json
워크스페이스 안이면 루트 package.json의 akanjs와 @akanjs/devkit을 그 버전으로 바꾸고 bun install을 실행합니다.
전역 설치
@akanjs/cli@<tag>를 bun add -g로 전역 설치하고, 끝에 akan --version을 출력합니다.
--registry local
npm에 배포하기 전의 프레임워크 빌드를 로컬 레지스트리에서 받아 시험합니다.
프레임워크 저장소
USE_AKANJS_PKGS=true이면 --registry에 기본값이 없어 CLI가 물어봅니다.
예시

download-env

이 워크스페이스의 모든 앱과 라이브러리의 env 값을 내려받습니다. env 값은 커밋되지 않으므로, clone한 직후와 누군가 변경을 올렸을 때마다 실행합니다.
형식
옵션
--hostString기본값 cloud.host, 없으면 Akan Cloud
AKAN_WORKSPACE_ID가 있을 때 쓸 클라우드이며 login과 같은 방식으로 정합니다. SCP 서버를 쓸 때는 무시합니다.
참고
보관 위치
루트 .env에 AKAN_WORKSPACE_ID가 있으면 Akan Cloud, 없으면 SCP 서버입니다.
파일
upload-env가 묶은 경로 그대로 워크스페이스 루트에 풀어 덮어씁니다.
첫 SCP 실행
서버 이름과 호스트, 그리고 비워 둘 수 있는 사용자 이름과 SSH 포트를 묻습니다.
서버 목록
~/.akan/config.json에 저장되어, 다음부터는 서버를 고르거나 추가하거나 지웁니다.
예시

upload-env

모든 앱과 라이브러리의 env 값을 download-env가 읽는 곳으로 올립니다. 보관된 압축본은 통째로 바뀌므로, 오래된 로컬 사본을 올리지 말고 먼저 내려받습니다.
형식
옵션
--hostString기본값 cloud.host, 없으면 Akan Cloud
AKAN_WORKSPACE_ID가 있을 때 쓸 클라우드이며 login과 같은 방식으로 정합니다. SCP 서버를 쓸 때는 무시합니다.
참고
보관 위치
루트 .env에 AKAN_WORKSPACE_ID가 있으면 Akan Cloud, 없으면 SCP 서버입니다.
env 파일
env/env.client.<env>.ts와 env/env.server.<env>.ts이며, type, example 파일은 빠집니다.
secrets
앱의 akan.config.ts에 적은 secrets glob에 맞는 파일도 함께 올립니다.
.gitignore
올릴 때마다 그 secrets 패턴을 .gitignore 안에서 akan이 관리하는 구역에 적습니다.
파일 없음
올릴 env 파일이 하나도 없으면 오류로 멈춥니다.
예시

upload-secret

AKAN_WORKSPACE_ID가 가리키는 프로젝트, --subspace를 주면 그 subspace의 프로젝트에서 파이프라인 step이 쓸 시크릿을 이름을 붙여 저장합니다. 값은 쓰기 전용이라 어떤 명령으로도 다시 볼 수 없으니, 원본은 다른 자격 증명과 같은 곳에 보관합니다.
형식
인자
nameString필수
대문자, 숫자, _로 된 64자 이하의 이름으로, 글자로 시작합니다. 예: DISCORD_WEBHOOK. 이 형식이 아니면 이름을 되풀이하지 않고 거부합니다. 잘못 친 이름이 값 자체일 수 있기 때문입니다.
옵션
--branchString기본값 모든 브랜치debug | develop | main
그 브랜치의 빌드에서만 이 값을 쓰며, 모든 브랜치용 값보다 우선합니다.
--fileString
stdin이나 숨김 입력 대신 이 파일에서 값을 읽습니다.
--subspaceString
루트 akan.config.ts의 subspace입니다. 그 workspaceId가 가리키는 프로젝트를 씁니다. 생략하면 AKAN_WORKSPACE_ID가 가리키는 프로젝트입니다.
--hostString기본값 cloud.host, 없으면 Akan Cloud
사용할 클라우드입니다. 생략하면 루트 akan.config.ts의 cloud.host, 없으면 https://cloud.akanjs.com입니다(프레임워크 저장소(USE_AKANJS_PKGS=true)에서는 http://localhost:8283).
참고
값
--file, 파이프로 넘긴 stdin, 숨김 입력 중 하나로 받습니다. 셸 기록에 남는 인자로는 받지 않습니다.
stdin
stdin에서 읽을 때는 그렇다는 한 줄을 stderr에 쓰고, 값은 쓰지 않습니다. stdin이 파이프로 이어져 있으면 빠진 <name>을 묻지 않고 오류로 멈추므로, 파이프로 넘긴 값을 이름으로 받는 일이 없습니다.
순서
이름과 --branch는 값을 읽거나 로그인하기 전에 검사합니다.
크기
빈 값이나 64 KiB를 넘는 값은 거부하고, 끝의 줄바꿈 하나는 뗍니다.
예약된 이름
CI, 모든 AKAN_CI_*, PATH 같은 셸 이름은 거부합니다.
적용 시점
올린 뒤에 시작하는 빌드부터 새 값을 씁니다.
예시

list-secrets

프로젝트의 파이프라인 시크릿을 범위, 마지막으로 바꾼 사람과 함께 나열합니다. 값은 보여 주지 않습니다.
형식
옵션
--branchStringdebug | develop | main
그 브랜치의 빌드가 쓰는 것만 보여 줍니다. 그 브랜치 전용 값과 모든 브랜치용 값입니다.
--subspaceString
루트 akan.config.ts의 subspace입니다. 그 workspaceId가 가리키는 프로젝트를 씁니다. 생략하면 AKAN_WORKSPACE_ID가 가리키는 프로젝트입니다.
--hostString기본값 cloud.host, 없으면 Akan Cloud
사용할 클라우드입니다. 생략하면 루트 akan.config.ts의 cloud.host, 없으면 https://cloud.akanjs.com입니다(프레임워크 저장소(USE_AKANJS_PKGS=true)에서는 http://localhost:8283).
참고
열
NAME, SCOPE(every branch 또는 브랜치 이름), UPDATED, BY입니다. 마지막으로 바꾼 사람처럼 프로젝트가 모르는 칸은 -로 보여 줍니다.
예시

remove-secret

프로젝트에서 파이프라인 시크릿을 지웁니다. 지운 뒤에 시작하는 빌드는 그 값을 받지 않습니다.
형식
인자
nameString필수
지울 시크릿의 이름입니다.
옵션
--branchString기본값 모든 브랜치debug | develop | main
그 브랜치 전용 값을 지웁니다. 없으면 모든 브랜치용 값을 지웁니다.
--subspaceString
루트 akan.config.ts의 subspace입니다. 그 workspaceId가 가리키는 프로젝트를 씁니다. 생략하면 AKAN_WORKSPACE_ID가 가리키는 프로젝트입니다.
--hostString기본값 cloud.host, 없으면 Akan Cloud
사용할 클라우드입니다. 생략하면 루트 akan.config.ts의 cloud.host, 없으면 https://cloud.akanjs.com입니다(프레임워크 저장소(USE_AKANJS_PKGS=true)에서는 http://localhost:8283).
참고
없는 시크릿
없는 시크릿을 지우면 그렇다고 알리고 아무것도 바꾸지 않습니다.
예시
다음명령어

MIT 라이선스 하에 배포되었습니다.

내 AI에 이 문서 연결하기

MCPhttps://akanjs.com/mcp
Copyright © 2026 Akan.js 모든 권리 보유.시스템 관리자bassman