터미널에서 문서 읽고 쓰기

브라우저를 열지 않고 문서를 다루고 싶을 때가 있습니다. 로컬에서 쓴 .md 파일을 올리거나, 매일 도는 스크립트가 결과를 문서에 남기거나, AI 코딩 도구가 문서를 읽어 가게 할 때입니다. 명령줄 도구 rawdoc이 그 일을 합니다.

Node 22 이상이 필요합니다.

브라우저가 열리고 승인 화면이 뜹니다. 승인하면 토큰이 이 컴퓨터에 저장되고, 터미널에 로그인한 계정이 찍힙니다. rawdoc whoami로 다시 확인할 수 있습니다. 브라우저가 열리지 않으면 터미널에 찍힌 주소를 통째로 복사해 브라우저에 붙여 넣습니다. 주소가 잘리면 로그인 주소가 잘렸거나 올바르지 않습니다.가 뜹니다.

설치 없이 한 번만 쓰려면 앞에 npx -y를 붙입니다.

npx -y rawdoc login

SSH나 컨테이너처럼 브라우저가 그 기계에 닿지 않는 곳에서는 웹의 계정 메뉴 → API 토큰에서 토큰을 만들어 표준 입력으로 넘깁니다.

rawdoc login --with-token < token.txt

자주 쓰는 명령

명령	하는 일
`rawdoc ls`	내 문서 목록
`rawdoc ls --path`	폴더 경로를 붙여 목록 보기(폴더에 안 든 문서는 `/`)
`rawdoc ls --root`	폴더에 안 든 문서만 보기
`rawdoc ls --shared`	공유받은 문서 목록
`rawdoc find 회의`	제목에 그 글자가 든 문서 찾기
`rawdoc search 회의`	제목·본문에서 그 글자가 든 문서와 줄 찾기(금고 문서 제외)
`rawdoc replace 옛말 새말 --yes`	여러 문서 본문에서 글자를 찾아 바꾸기(`--yes`를 빼면 바뀔 곳만 미리 보기. `--id <id>`면 그 문서 하나만)
`rawdoc info <id>`	내용 없이 폴더·판 번호·시각만 보기
`rawdoc get <id> -o 노트.md`	문서 원문을 파일로 받기(판 번호는 옆 파일 `노트.md.rawdoc`에 적힘)
`rawdoc new 노트.md --title 회의록`	파일로 새 문서 만들기
`rawdoc diff <id> 노트.md`	올리기 전에 서버 문서와 바뀌는 줄 보기
`rawdoc put <id> 노트.md --base-version auto`	문서 고치기(성공하면 웹 주소도 찍음)
`rawdoc merge <id> 노트.md`	그 사이 바뀐 서버 문서를 내 파일에 합치기
`rawdoc folders` · `rawdoc mkdir <이름> [--parent <폴더id\|경로>]`	폴더 보기·만들기(`--parent`를 빼면 맨 위에 만듦)
`rawdoc upload 그림.png`	이미지를 올리고 붙일 마크다운 받기
`rawdoc link <id>`	읽기 전용 링크 만들기
`rawdoc mv <id> --folder <폴더id\|경로>`	문서 옮기기(`--root` 면 맨 위로)
`rawdoc rm <id> --yes` · `rawdoc rmdir <id> --yes`	문서·폴더 지우기(되돌릴 수 없음. `rmdir` 은 안의 것을 위 폴더로 올리고, `--all` 이면 모두 지움)
`rawdoc syntax`	이 앱에서 쓰는 마크다운 문법을 터미널에 출력(`--short`면 이 앱에만 있는 문법만)

금고 문서나 금고 폴더가 걸린 지우기·옮기기는 웹에서 합니다.

폴더를 받는 옵션(new·mv·ls·find·search·replace의 --folder, mkdir의 --parent)에는 폴더 id 대신 folders가 보여 주는 경로(예: 수업자료/1주차)를 넣어도 됩니다. 경로에 맞는 폴더가 없거나 같은 경로의 폴더가 여럿이면 멈추고, rawdoc folders로 id를 확인하라고 알려 줍니다. rmdir은 id만 받습니다.

명령마다 사용법과 옵션 설명은 rawdoc help <명령>으로 봅니다. rawdoc <명령> --help와 같습니다.

모든 명령은 --json을 받습니다. 스크립트에서 결과를 다룰 때 씁니다.

원문은 그대로

get은 문서에 든 글자를 한 글자도 바꾸지 않고 내보냅니다. 앱의 .md 내보내기와 같은 원칙입니다.

올릴 때(new·put)는 앱의 가져오기와 같은 정리를 거칩니다. 섞인 줄바꿈은 하나로 맞추고, 파일 앞의 BOM은 떼어 냅니다. 그때는 표준 오류에 안내가 뜹니다. put한 파일의 줄바꿈(CRLF·LF)이 서버 문서와 다를 때도 서버 문서 방식으로 저장하고 표준 오류로 알려 줍니다. 로컬 파일은 바뀌지 않습니다.

Windows PowerShell 5.1에서 >로 출력을 파일에 받으면 한글이 깨집니다. get -o 파일.md를 쓰세요.

덮어쓰기를 막는 장치

put에는 --base-version으로 내가 읽은 판 번호를 함께 넘깁니다. 그 사이 다른 곳에서 문서가 바뀌었으면 덮어쓰지 않고 종료 코드 5로 멈춥니다.

판 번호는 내용과 같은 get에서 받아야 합니다. get 문서id -o 노트.md는 파일과 함께 판 번호와 받은 원문을 옆 파일 노트.md.rawdoc에 적어 둡니다. 그 파일을 고친 뒤 put 문서id 노트.md --base-version auto로 올리면 적어 둔 번호를 쓰고, 성공하면 새 번호로 고쳐 적습니다. 번호만 따로 다시 읽고 옛 내용을 올리면 번호는 맞아도 그 사이 저장분을 덮어씁니다.

종료 코드 5로 멈췄다면 merge 문서id 노트.md로 받았던 원문·내 파일·서버의 지금 문서를 줄 단위로 합칩니다. 같은 곳을 양쪽에서 고쳤으면 파일에 <<<<<<< 내 파일 ~ >>>>>>> 서버 판 N 표시가 남고 종료 코드 5로 끝납니다. 표시를 정리한 뒤 다시 put합니다. 표시가 남은 파일은 put이 올리지 않습니다.

--force는 서버의 지금 판 위에 확인 없이 덮어씁니다. 그 사이 다른 곳에서 고친 내용이 사라지므로 멈춘 뒤 다시 받아 고치는 쪽을 먼저 택합니다.

put --dry-run은 서버에 쓰지 않고 바뀌는 줄 수(추가·삭제)와 줄바꿈 방식만 보여 줍니다. --diff를 붙이면 바뀌는 줄도 보여 줍니다. 쓰기 권한과 용량은 확인하지 않습니다.

제목을 바꾸면 그 제목으로 건 [[위키링크]]가 끊길 수 있습니다. 이 안내는 put --help·mv --help·syntax에도 나옵니다. put은 올리는 본문의 위키링크가 내 문서 어디에도 맞지 않으면 표준 오류에 경고만 찍고 그대로 올립니다.

브라우저에서 누군가 그 문서를 치는 중이면 종료 코드 5로 멈출 수 있습니다. 다시 받아 고치거나, 치기가 멈춘 뒤 다시 시도합니다. 드물게 실시간 연결이 안 된 브라우저가 문서를 잡고 있으면 종료 코드 6으로 멈춥니다.

스크립트·AI 도구에서 쓰기

토큰을 파일에 저장하지 않고 환경 변수로 넘길 수 있습니다.

RAWDOC_TOKEN=... npx -y rawdoc ls --json

-y는 처음 실행할 때 나오는 설치 확인을 건너뜁니다. 대화형 입력을 받을 수 없는 AI 도구에서 부를 때 이 형태를 씁니다.

AI 도구에 문서를 쓰게 한다면 이 앱의 마크다운 문법을 먼저 읽게 하세요. 콜아웃(> [!note] 제목)이나 위키링크([[문서 제목]])처럼 일반 마크다운에 없는 문법이 있습니다. 문법을 한 곳에 모은 곳은 도움말의 마크다운 문법 절이고, 자세한 설명은 콜아웃·수식·다이어그램 쓰기와 위키링크로 문서 잇기에 있습니다.

도움말을 열 수 없는 환경에서는 npx -y rawdoc syntax를 실행하게 하세요. 로그인 없이, 서버에 연결하지 않고 문법표를 출력합니다. 설치된 판에 든 표라서 새 문법은 도움말에 먼저 반영됩니다.

한도

계정마다 쓰기는 1분에 120번·하루 5,000번, 문서는 모두 합쳐 100MB·10,000개까지입니다. 쓰기 한도에 걸리면 종료 코드 8로 멈추고 기다릴 시간을 알려 줍니다. 하루 한도는 한국 시간 오전 9시에 풀립니다. 저장 공간이 차면 종료 코드 7로 멈춥니다. 문서를 지우거나 줄이면 다시 올릴 수 있습니다.

로그아웃

rawdoc logout은 이 컴퓨터에 저장한 토큰만 지웁니다. 서버에 남은 토큰까지 없애려면 웹의 계정 메뉴 → API 토큰에서 폐기합니다.