개요
aktar는 같은 컴퓨터에 있는 Aktar 앱을 조작하는 리모컨입니다. 파일을 넘기면 127.0.0.1에서 실행 중인 Aktar에 전달되고, Aktar가 이미 설정해 둔 대상, 키, 경로 템플릿, 링크 설정 그대로 업로드합니다. 링크는 터미널로 돌아옵니다.
할 수 있는 일
- 스크립트, 내 Mac이나 Windows 컴퓨터에서 돌리는 CI 작업, Typora 같은 편집기에서 쓰는 작은 Node.js 명령어
- 파일과 클립보드 업로드, QR 코드 표시, 대상 목록과 업로드 기록 조회
- 앱과 마찬가지로 무료 오픈 소스(MIT)
할 수 없는 일
- 단독으로는 동작하지 않습니다. Aktar가 실행 중이 아니면 아무것도 업로드할 수 없고, 스토리지 키를 보관하지도 않습니다
- Linux 서버나 원격 컴퓨터용이 아닙니다. 같은 컴퓨터의 Aktar하고만 통신합니다. 그런 환경에서는 스토리지 제공업체의 CLI를 사용하세요
요구 사항
- 대상이 하나 이상 있는 Aktar for Mac 0.18.0 또는 Aktar for Windows 0.11.0 이상. aktar 0.5.0 이하는 Aktar for Mac 0.4.0 이상에서 작동합니다
- Node.js 18 이상(Homebrew로 설치하면 함께 설치됩니다)
-
--name,--qr,aktar qr에는 aktar 0.2.0 이상이 필요합니다 - 이미 업로드된 파일의 링크를 재사용하려면 aktar 0.2.0과 Aktar for Mac 0.10.0 또는 Aktar for Windows 0.3.0이 필요합니다
-
aktar replace에는 aktar 0.3.0과 Aktar for Mac 0.14.0 또는 Aktar for Windows 0.7.0 이상이 필요합니다 -
--short,--no-short,aktar short에는 aktar 0.5.0과 Mac용 Aktar 0.17.0 또는 Windows용 Aktar 0.10.0, 그리고 대상에 설정한 링크 단축기가 필요합니다
설치
npm이나 Homebrew로 한 번만 설치하면 됩니다. 어느 쪽이든 aktar 명령어가 PATH에 추가됩니다.
npm으로 설치(macOS, Windows)
npm install -g @getaktar/cliHomebrew로 설치(macOS)
brew install getaktar/tap/aktar-cli설치하지 않고 한 번만 실행할 수도 있습니다:
npx @getaktar/cli upload file.png설치된 버전 확인:
aktar --version
0.6.0Aktar에 연결하기
- Aktar for Mac 또는 Windows에서 설정 > 연동을 열고 로컬 연결 허용을 켭니다. 그러면 Aktar는
127.0.0.1에서만 연결을 받으며, 포트는 따로 바꾸지 않는 한 47913입니다. - 그 아래에 표시된 토큰을 복사합니다.
aktar login을 실행하고Token:프롬프트에 토큰을 붙여 넣습니다. 입력하는 동안 토큰은 화면에 표시되지 않으며, 저장하기 전에 Aktar에서 확인하므로 잘못 입력한 토큰은 저장되지 않습니다.
aktar login
Copy the token from Aktar: Settings > Integrations (turn on Allow local connections first).
Token:
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.json토큰이 저장되는 위치
aktar login은 토큰과 포트를 Mac에서는 ~/.config/aktar/cli.json(설정했다면 $XDG_CONFIG_HOME/aktar/cli.json)에, Windows에서는 %APPDATA%\aktar\cli.json에 저장합니다. 이 파일은 내 사용자 계정만 읽을 수 있습니다.
토큰을 보내기 전에 aktar는 포트에 있는 앱에 같은 토큰을 가지고 있음을 증명하도록 요청합니다. 이때 토큰 자체는 보내지 않습니다. 그래서 Aktar가 실행 중이 아니고 다른 프로그램이 그 포트에서 대기하고 있어도, 그 프로그램은 토큰도 파일도 받지 못합니다. 이 기능에는 Aktar for Mac 0.18.0 또는 Aktar for Windows 0.11.0 이상이 필요하며, 더 오래된 Aktar에서는 aktar가 멈추고 업데이트하라고 안내합니다.
aktar logout은 이 파일을 삭제합니다. 모든 클라이언트의 접근을 한꺼번에 막으려면 Aktar에서 토큰 옆의 다시 생성을 클릭한 다음, 새 토큰으로 aktar login을 다시 실행하세요.
스크립트와 CI
빌드 머신에서는 aktar login 대신 AKTAR_TOKEN을 설정하세요(포트를 바꿨다면 AKTAR_PORT도). 이 값들은 저장된 파일보다 우선합니다. 해당 머신에서 같은 사용자 세션으로 로그인한 상태로 Aktar가 실행 중이어야 합니다.
AKTAR_TOKEN="$AKTAR_SECRET" aktar upload dist/app.zip -d Builds| 변수 | 역할 |
|---|---|
AKTAR_TOKEN | Aktar의 설정 > 연동에 있는 토큰입니다. 저장된 토큰 대신 사용됩니다. |
AKTAR_PORT | 포트를 바꿨다면 Aktar 로컬 API의 포트입니다. --port가 이 값보다 우선합니다. |
NO_COLOR | QR 코드를 터미널 색상 대신 일반 문자로 그립니다. |
XDG_CONFIG_HOME | macOS에서 설정 폴더의 위치입니다(기본값 ~/.config). Windows에서는 %APPDATA%를 사용합니다. |
명령어
일반 텍스트나 링크를 넘긴 aktar qr을 제외하면 모든 명령어가 Aktar와 통신합니다. -d를 생략하면 Aktar 메뉴 막대에서 선택된 대상으로 업로드되고, 다른 업로드와 똑같이 Aktar 기록에 남습니다. aktar --help로도 같은 목록을 볼 수 있습니다. Aktar for Mac 0.14.0 또는 Aktar for Windows 0.7.0 이상에서는 -d 없는 업로드가 먼저 대상의 용도 규칙을 따르므로, 이미지는 스크린샷용 대상으로, 빌드는 다른 대상으로 보낼 수 있습니다.
aktar uploadaktar upload --clipboardaktar replaceaktar shortaktar qraktar loginaktar logoutaktar statusaktar destinationsaktar historyaktar mcpaktar skill
aktar upload
파일을 하나 이상 업로드하고, 각 파일이 끝날 때마다 파일 순서대로 링크를 하나씩 출력합니다.
사용법
aktar upload <file>... [options]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
-d, --destination | <name|id> | 업로드할 대상의 이름 또는 ID입니다. 기본값: Aktar에서 선택된 대상. |
-f, --format | <format> | 출력할 형식: url(기본값), markdown, html, custom(Aktar에서 만든 템플릿). |
--name | <name> | 파일 하나를 이 이름으로 업로드합니다. 이름에 확장자가 없으면 원래 확장자가 유지됩니다. |
--folder | <path> | 파일 이름을 그대로 두고 이 폴더에 업로드합니다. |
--expires | <days> | 1, 7, 14, 30일 후 버킷이 파일을 삭제하게 합니다. 0이면 보관합니다. |
--short | 대상의 규칙상 건너뛸 업로드라도 대상의 링크 단축기로 짧은 링크를 만듭니다. | |
--no-short | 이번에는 짧은 링크를 만들지 않습니다. | |
--qr | 각 링크의 QR 코드도 함께 출력합니다. | |
--json | 링크 대신 각 업로드의 자세한 정보를 담은 JSON 배열을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 업로드를 시작하기 전에 모든 파일을 확인합니다. 존재하지 않는 파일이 하나라도 있으면 아무것도 업로드하지 않고
aktar가 종료 코드 2로 끝납니다. - 업로드 하나가 실패해도 나머지는 계속 진행됩니다. 실패한 항목은 각각 stderr에 표시되고 종료 코드는 1이 됩니다.
--folder가 없으면 메뉴 막대에 파일을 끌어다 놓을 때처럼 대상의 경로 템플릿이 파일 이름을 정합니다.--folder를 쓰면 파일이 원래 이름 그대로 그 폴더에 들어갑니다.--name은 한 번에 파일 하나에만 쓸 수 있습니다. 슬래시는 제거되고, 이름에 확장자가 없으면 원래 파일의 확장자가 붙습니다. 예를 들어--name cover를 쓰면IMG_4021.jpg가cover.jpg로 업로드됩니다.--folder와 함께 쓰면 폴더 안에서의 이름이 됩니다.--expires에는 1, 7, 14, 30(일) 또는 파일을 계속 보관하는 0을 지정합니다. 이 옵션이 없으면 Aktar의 보관 기간 설정과 관계없이 파일이 보관됩니다. 해당 대상에 Aktar의 자동 삭제 규칙이 설정되어 있어야 하며,--folder와 함께 쓸 수 없습니다.--qr은--json과 함께 쓸 수 없고,--png는aktar qr에서만 동작합니다.- 터미널에서는 업로드하는 동안 진행 상황이 stderr에 표시됩니다. 파일은 Aktar로 스트리밍되므로 크기는 상관없고 시간 제한도 없습니다.
- 대상에 Aktar의 링크 단축기가 설정되어 있으면 짧은 링크가 출력되고,
--format과--qr도 그 링크를 사용합니다.--short는 대상의 규칙상 건너뛸 업로드라도 짧은 링크를 만들고,--no-short는 만들지 않습니다. Aktar가 만들지 못하면 원래 링크가 출력되고 이유는 stderr에 표시됩니다.
예시
aktar upload screenshot.png
https://files.example.com/2026/10/7f3c2a91.pngaktar upload *.png -f markdown

aktar upload IMG_4021.jpg --name cover --folder blog/2026
https://files.example.com/blog/2026/cover.jpgaktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpgaktar upload talk.pdf --short
https://s.example.com/k3Tq9aktar upload --clipboard
Aktar 자체의 클립보드 단축키처럼, 클립보드에 있는 파일이나 이미지를 업로드합니다.
사용법
aktar upload --clipboard [options]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--clipboard | 파일 대신 클립보드에 있는 항목을 업로드합니다. | |
-d, --destination | <name|id> | 업로드할 대상의 이름 또는 ID입니다. 기본값: Aktar에서 선택된 대상. |
-f, --format | <format> | 출력할 형식: url(기본값), markdown, html, custom(Aktar에서 만든 템플릿). |
--expires | <days> | 1, 7, 14, 30일 후 버킷이 파일을 삭제하게 합니다. 0이면 보관합니다. |
--short | 대상의 규칙상 건너뛸 업로드라도 대상의 링크 단축기로 짧은 링크를 만듭니다. | |
--no-short | 이번에는 짧은 링크를 만들지 않습니다. | |
--qr | 각 링크의 QR 코드도 함께 출력합니다. | |
--json | 링크 대신 각 업로드의 자세한 정보를 담은 JSON 배열을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 파일과
--clipboard중 하나만 지정하세요. 둘을 함께 쓸 수는 없습니다. --name과--folder는 파일에서만 동작합니다.-d,-f,--expires,--qr,--json은 파일을 업로드할 때와 똑같이 동작합니다.--json을 쓰면 항목이 하나인 배열을 출력합니다.
예시
aktar upload --clipboard
https://files.example.com/2026/10/9a4c03be.pngaktar upload --clipboard -f markdown -d Blog
aktar upload --clipboard --expires 1
https://files.example.com/tmp/1d/2026/10/38f0d7c2.pngaktar replace
업로드된 파일을 새 파일로 덮어써서 키와 링크를 그대로 유지합니다. 링크를 가진 사람은 모두 새 파일을 보게 됩니다.
사용법
aktar replace <upload-id|link|key> <file> [options]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
-d, --destination | <name|id> | 키를 지정할 때, 그 키가 있는 버킷의 대상 이름 또는 ID입니다. 기본값: Aktar에서 선택된 대상. |
-f, --format | <format> | 출력할 형식: url(기본값), markdown, html, custom(Aktar에서 만든 템플릿). |
--qr | 각 링크의 QR 코드도 함께 출력합니다. | |
--json | 링크 대신 각 업로드의 자세한 정보를 담은 JSON 배열을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 첫 번째 인수는
aktar history에 나오는 업로드 ID나 링크(Aktar 기록 항목도 함께 업데이트됨)이고, 그 밖의 값은-d대상 버킷의 키로 처리됩니다(생략하면 Aktar에서 선택된 대상). Aktar 기록에 없는 링크는 거부되므로, 그럴 때는 키를-d와 함께 넘기세요. - Aktar는 대상 설정에 따라 파일의 메타데이터를 제거하고 크기를 조절하지만, 다른 형식으로 변환하지는 않으므로 키의 확장자는 그대로입니다.
tmp/{N}d/아래의 파일은 N일이 처음부터 다시 시작됩니다. - 키에 번호가 붙지 않으며 다른 파일은 업로드되지 않습니다.
--folder,--expires,--name,--clipboard는 적용되지 않으며 거부됩니다. - 이전 파일이 CDN 캐시에 한동안 남을 수 있습니다. 대상의 짧은 캐시 시간이나 Aktar의 Cloudflare 캐시 삭제 기능으로 해결할 수 있습니다.
- Aktar for Mac 0.14.0 또는 Aktar for Windows 0.7.0 이상이 필요합니다.
예시
aktar replace 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 report-v2.pdf
https://files.example.com/2026/09/0e7d51b3.pdfaktar replace docs/guide.pdf guide.pdf -d Blog -f markdown
[guide.pdf](https://blog-assets.example.com/docs/guide.pdf)aktar short
기록에 있는 업로드의 짧은 링크를 대상의 링크 단축기로 만들어 출력합니다. 이미 짧은 링크가 있으면 그 링크를 출력합니다.
사용법
aktar short <upload-id|link> [--json | --qr]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--json | 짧은 링크의 세부 정보를 JSON으로 출력합니다: 제공자, 상태, 클릭 수. | |
--qr | 짧은 링크의 QR 코드도 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 업로드 ID나
aktar history의 링크를 넘기세요. 짧은 링크도 됩니다.aktar는 최근 1,000개의 업로드에서 찾습니다. - 대상에 Aktar의 짧은 링크 섹션에서 링크 단축기를 설정해야 합니다: Shlink, YOURLS, Kutt, Dub, Short.io 또는 사용자 지정 요청. 짧은 링크는 그 단축기가 만들므로 링크와 클릭 데이터는 사용자의 인프라에 남습니다.
--json은 짧은 링크의 세부 정보를 출력합니다: 제공자, 상태, 단축기가 집계하는 경우 클릭 수와 마지막 클릭.--qr는 QR 코드를 덧붙입니다. 둘은 함께 쓸 수 없습니다.- Mac용 Aktar 0.17.0 또는 Windows용 Aktar 0.10.0이 필요합니다. 이전 버전은 아직 짧은 링크를 만들 수 없다고 답합니다.
예시
aktar short 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1
https://s.example.com/Qm3xZaktar qr
링크나 임의의 텍스트를 QR 코드로 터미널에 표시해 휴대폰에서 바로 열 수 있게 합니다. 업로드 ID를 넘기면 해당 업로드의 링크와 QR 코드를 보여 줍니다.
사용법
aktar qr <link|text|upload-id> [--png <file>]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--png | <file> | QR 코드를 출력하는 대신 PNG 파일로 저장합니다. |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 인수는 정확히 하나만 넘기고, 공백이 있는 텍스트는 따옴표로 감싸세요.
- 업로드 ID는
aktar history --json이나aktar upload --json의id입니다.aktar는 Aktar 기록의 최근 업로드 1,000개에서 이 ID를 찾습니다. 일반 텍스트나 링크라면 Aktar가 전혀 필요 없습니다. - 터미널에서는 테마와 관계없이 흰 바탕에 검은색으로 코드를 그립니다. 출력이 터미널이 아니거나
NO_COLOR가 설정되어 있으면 색상 없이 그립니다. --png를 쓰면 QR 코드를 출력하는 대신 PNG로 저장합니다.- 짧은 링크가 있는 업로드라면 짧은 링크를 보여 줍니다.
예시
aktar qr https://files.example.com/2026/10/demo.mp4aktar qr 0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1 --png cover-qr.png
Saved to cover-qr.pngaktar login
토큰을 Aktar에서 확인한 뒤 저장해 다른 명령어가 연결할 수 있게 합니다.
사용법
aktar login [--token <token>] [--port <port>]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--token | <token> | 프롬프트 대신 넘기는 토큰입니다. |
--port | <port> | 토큰과 함께 저장할 Aktar 포트입니다. 기본값 47913. |
알아 두면 좋은 점
- 터미널에서는 토큰을 입력하라고 묻고, 입력 내용을 숨깁니다. 입력이 파이프로 들어오면 거기서 토큰을 읽습니다.
--token을 쓰면 프롬프트를 건너뛰지만, 명령이 실행되는 동안 다른 프로그램이 토큰을 볼 수 있고 셸 기록에도 남기 때문에aktar가 경고합니다. 파이프로 넘기거나AKTAR_TOKEN을 쓰면 이를 피할 수 있습니다.- Aktar가 거부한 토큰은 저장되지 않으며 종료 코드는 3입니다.
예시
aktar login
Copy the token from Aktar: Settings > Integrations (turn on Allow local connections first).
Token:
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.jsonpbpaste | aktar login
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.jsonaktar가 토큰이 노출되었다고 경고합니다.aktar login --token "$AKTAR_SECRET" --port 47920
aktar: warning: a token on the command line can be seen by other programs (ps) and stays in your shell history. Next time, run aktar login without --token and paste it, or pipe it in.
Connected to Aktar 0.10.0. Saved to /Users/you/.config/aktar/cli.jsonaktar logout
저장된 토큰과 포트를 삭제합니다.
사용법
aktar logout옵션
옵션이 없습니다.
알아 두면 좋은 점
AKTAR_TOKEN이 설정되어 있다면aktar logout후에도 계속 동작합니다.- 다른 클라이언트의 연결은 끊지 않습니다. 그러려면 Aktar에서 토큰을 다시 생성하세요.
예시
aktar logout
Logged out.aktar status
aktar: Not connected to Aktar yet. Run aktar login with the token from Aktar's Settings > Integrations.aktar status
연결된 Aktar와 포트, Aktar에서 선택된 대상, 설정 파일의 위치를 보여 줍니다.
사용법
aktar status [--json]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--json | 텍스트 대신 JSON을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 스크립트에서 연결을 빠르게 확인하는 방법입니다. Aktar에 연결할 수 없거나 토큰이 틀리면 종료 코드 3으로 끝납니다.
예시
aktar status
Aktar 0.10.0 (build 28) on port 47913
Destination: Screenshots (Cloudflare R2, screenshots)
Config: /Users/you/.config/aktar/cli.jsonaktar status --json
{
"app": "Aktar",
"version": "0.10.0",
"build": "28",
"apiVersion": 1,
"defaultDestinationId": "5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47",
"outputFormat": "url",
"port": 47913
}aktar destinations
대상 목록을 제공업체, 버킷, ID와 함께 보여 줍니다. *는 Aktar에서 선택된 대상을 나타냅니다.
사용법
aktar destinations [--json]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--json | 텍스트 대신 JSON을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
-d에는 이름이나 ID를 쓰세요. 이름은 대소문자를 구분하지 않고 찾으며, ID는 이름을 바꾼 뒤에도 항상 동작합니다.--json은 각 대상의id,name,provider,providerName,bucket,publicBaseURL,isDefault를 출력합니다.
예시
aktar destinations
* Screenshots Cloudflare R2 screenshots 5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47
Builds Amazon S3 acme-builds A83F2C10-6D4B-4F7E-9C1A-2B5E8D0F3C66
Blog Backblaze B2 blog-assets E2C7B9A4-1F3D-4A8E-B6C0-9D5F2A7E4B13aktar destinations --json | jq -r '.[] | select(.isDefault) | .name'
Screenshotsaktar history
최근 업로드를 최신순으로 날짜, 파일 이름, 링크와 함께 보여 줍니다. history 뒤에 단어를 붙이면 기록에서 검색합니다.
사용법
aktar history [search] [options]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
-n, --limit | <n> | 보여 줄 업로드 개수입니다. 기본값 20. |
-d, --destination | <name|id> | 이 대상(이름 또는 ID)에 업로드한 항목만 보여 줍니다. |
--json | 텍스트 대신 JSON을 출력합니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
-n을 지정하지 않으면 업로드 20개를 보여 줍니다.--json은aktar upload --json과 같은 필드를 출력하며,aktar qr에 쓸 수 있는 각 업로드의id도 포함합니다.
예시
aktar history -n 3
2026-10-01 screenshot.png https://files.example.com/2026/10/7f3c2a91.png
2026-10-01 cover.jpg https://files.example.com/blog/2026/cover.jpg
2026-09-30 invoice-september.pdf https://files.example.com/2026/09/0e7d51b3.pdfaktar history invoice -d Screenshots
2026-09-30 invoice-september.pdf https://files.example.com/2026/09/0e7d51b3.pdf
2026-08-29 invoice-august.pdf https://files.example.com/2026/08/a6c94f20.pdfaktar history -d Builds -n 1 --json | jq -r '.[0].url'
https://acme-builds.s3.amazonaws.com/2026/10/app-3f9c2e1.zipaktar mcp
AI 에이전트(Claude, Cursor, VS Code, Codex 등)가 Aktar로 파일을 업로드하고, 지난 업로드를 찾고, 링크를 만들 수 있도록 Model Context Protocol(MCP) 서버를 실행합니다. 에이전트에 한 번만 추가해 두면 필요할 때 에이전트가 직접 시작합니다.
사용법
aktar mcp [--root <folder>]... [--read-only | --allow-replace | --allow-delete] [--max-link-minutes <n>] [--log <file>]옵션
| 플래그 | 값 | 설명 |
|---|---|---|
--root | <folder> | 이 폴더의 파일만 업로드합니다. 폴더를 더 추가하려면 반복해서 지정하세요. 기본값: 서버가 실행되는 폴더. 그 폴더가 홈 폴더나 디스크 최상위라면 없음. |
--read-only | 버킷에서 아무것도 바꾸지 않는 도구만 제공합니다: 검색, 목록, 임시 링크, 썸네일. | |
--allow-replace | 버킷의 파일을 덮어쓰는 replace_file도 제공합니다. | |
--allow-delete | 버킷에서 파일을 삭제하는 delete_upload와 replace_file도 제공합니다. | |
--max-link-minutes | <n> | 임시 링크가 작동할 수 있는 최대 시간(분). 기본값 60, 최대 10080(7일). |
--log | <file> | 각 도구 호출(시간, 도구, 인수, 결과)을 이 파일에 이어서 기록합니다. 이 파일은 나만 읽을 수 있습니다. |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
알아 두면 좋은 점
- 먼저
aktar login을 실행하세요. 서버는 호출할 때마다 저장된 토큰을 읽으므로, 다시 로그인해도 에이전트를 재시작할 필요가 없습니다. - 업로드는 파일을 공개하는 일입니다. 링크를 아는 사람은 누구나 열 수 있습니다. 에이전트는 허용하지 않는 한 도구를 호출하기 전에 먼저 물어봅니다.
- 파일은
--root로 지정한 폴더에서만 업로드되며, 지정하지 않으면 서버가 실행되는 폴더에서만 업로드됩니다. 일부 앱처럼 그 폴더가 홈 폴더나 디스크 최상위라면--root를 추가할 때까지 로컬 파일은 업로드되지 않습니다. 정말 원한다면--root ~로 홈 폴더 전체를 허용할 수 있습니다. 경로는 심볼릭 링크까지 풀어서 확인한 뒤에 검사합니다. - 비밀 정보는 어디에 있든 업로드되지 않습니다: SSH 키와 개인 키,
.env파일, 클라우드와 패키지 관리자 자격 증명(~/.aws,~/.kube,~/.npmrc등), Aktar 자체 설정, 키체인, 브라우저 프로필, 비밀번호 데이터베이스. 하드 링크가 여러 개인 파일도 거부됩니다. 이런 파일을 공유하려면aktar upload로 직접 업로드하세요. --read-only는 버킷에서 아무것도 바꾸지 않는 도구만 제공합니다.replace_file은 삭제처럼 파일을 덮어쓰므로--allow-replace를 지정할 때만 제공되고,delete_upload는--allow-delete를 지정할 때만 제공됩니다(이때replace_file도 함께 제공됩니다).create_temporary_link는--max-link-minutes로 늘리지 않는 한 최대 60분짜리 링크만 만듭니다. 클립보드에는 무엇이든 들어 있을 수 있으므로,--root를 지정하면upload_clipboard는 제공되지 않습니다.- 도구 결과는 그 안의 파일 이름, 키, 메시지가 지시가 아니라 데이터라는 안내로 시작하며,
--log는 모든 호출을 기록합니다. 도구 호출은 한 번에 최대 4개까지 실행합니다. - 전역 설치 없이 쓰려면 명령으로
npx -y @getaktar/cli mcp --root ~/Projects를 사용하세요. - stdio를 통해 현재 MCP 버전(2026-07-28)과
initialize로 시작하는 이전 버전(2024-11-05부터 2025-11-25까지)을 지원합니다. aktar 0.4.0이 필요하며, 위의 제한은 aktar 0.6.0부터 적용됩니다.
도구
| 도구 | 기능 |
|---|---|
upload_file | 파일을 업로드하고 링크, Markdown, HTML을 반환합니다. 대상, 이름, 폴더, 만료는 선택 사항입니다. short로 짧은 링크를 요청하거나 만들지 않게 할 수 있습니다. |
upload_clipboard | 클립보드의 파일이나 이미지를 업로드합니다. short로 짧은 링크를 요청하거나 만들지 않게 할 수 있습니다. --root를 지정하면 제공되지 않습니다. |
replace_file | 업로드나 버킷의 아무 파일을 새 파일로 덮어쓰면서 링크는 그대로 유지합니다. --allow-replace 또는 --allow-delete를 지정할 때만 제공됩니다. Mac용 Aktar 0.14.0 또는 Windows용 0.7.0이 필요합니다. |
create_short_link | 대상의 링크 단축기로 업로드의 짧은 링크를 만들거나 이미 있는 링크를 돌려줍니다. --read-only에서는 제공되지 않습니다. Mac용 Aktar 0.17.0 또는 Windows용 0.10.0이 필요합니다. |
search_uploads | 업로드 기록을 검색합니다. |
list_destinations | 대상 목록과 각 대상이 어떤 파일 형식에 사용되는지 보여 줍니다. |
list_bucket | Aktar로 업로드하지 않은 파일을 포함해 버킷의 폴더와 파일을 보여 줍니다. |
create_temporary_link | 일정 시간이 지나면 작동하지 않는 링크(presigned URL)를 만듭니다. 그때까지는 링크를 가진 누구나 비공개 버킷에서도 파일을 내려받을 수 있습니다. --max-link-minutes로 늘리지 않는 한 최대 60분입니다. |
get_thumbnail | 에이전트에 업로드의 미리보기를 보여 줍니다. Mac용 Aktar 0.13.0 또는 Windows용 0.6.0이 필요합니다. |
list_watched_folders | 감시 폴더와 그 상태를 보여 줍니다. |
get_status | Aktar와의 연결을 확인합니다. |
delete_upload | 버킷에서 업로드를 삭제합니다. --allow-delete를 지정했을 때만 제공됩니다. |
예시
claude mcp add aktar -- aktar mcp --root ~/Projects
codex mcp add aktar -- aktar mcp --root ~/Projectsclaude mcp add aktar -- aktar mcp --root ~/Projects --root ~/Desktop --allow-replaceclaude mcp add aktar -- aktar mcp --root ~/Projects --log ~/aktar-mcp.logaktar skill
에이전트가 aktar 명령을 --json과 함께 사용하는 방법(무엇을 실행할지, 결과를 어떻게 읽을지, 공유하라고 한 것만 업로드할 것)을 알려 주는 에이전트 스킬(SKILL.md)을 출력합니다. 스킬은 쓰지만 MCP는 쓰지 않는 에이전트용입니다.
사용법
aktar skill옵션
옵션이 없습니다.
알아 두면 좋은 점
- 에이전트가 스킬을 찾는 위치에 저장하세요. 예를 들어 Claude Code라면
~/.claude/skills/aktar/입니다.
예시
mkdir -p ~/.claude/skills/aktar
aktar skill > ~/.claude/skills/aktar/SKILL.md모든 명령어에 쓸 수 있는 옵션
| 플래그 | 값 | 설명 |
|---|---|---|
-h, --help | 명령어와 옵션 목록을 보여 줍니다. | |
-v, --version | aktar의 버전을 보여 줍니다. | |
--port | <port> | 이 명령어에만 적용되는 Aktar 로컬 API 포트입니다. AKTAR_PORT와 저장된 포트보다 우선합니다. |
출력
형식
-f로 업로드마다 무엇을 출력할지 고릅니다. 지정하지 않으면 Aktar 메뉴 막대가 어떤 형식으로 복사하든 aktar는 일반 URL을 출력합니다. Markdown과 HTML에서는 Aktar와 같은 방식으로 이미지는 삽입하고 그 밖의 파일은 링크로 넣습니다.
| 형식 | photo.jpg의 출력 |
|---|---|
-f url | https://files.example.com/2026/10/7f3c2a91.jpg링크(기본값). |
-f markdown | Markdown 이미지, 다른 파일은 Markdown 링크. |
-f html | <img src="https://files.example.com/2026/10/7f3c2a91.jpg" alt=""><img> 태그, 다른 파일은 <a> 링크. |
-f custom | Aktar 설정에서 만든 템플릿으로, {url}, {filename} 등의 변수가 채워집니다. |
stdout과 stderr
표준 출력에는 링크만 파일 순서대로 한 줄에 하나씩 나옵니다(--qr을 쓰면 QR 코드도). 나머지는 모두 표준 오류로 갑니다. 진행 상황, 오류, 그리고 aktar: photo.jpg: already uploaded, reused the existing link 같은 안내 메시지입니다. 그래서 url=$(aktar upload file)와 aktar upload *.png > links.txt는 항상 깔끔한 링크만 받습니다.
aktar upload photo.jpg
aktar: photo.jpg: already uploaded, reused the existing link
https://files.example.com/2026/09/4d2a8c61.jpgJSON
--json은 모든 업로드가 끝난 뒤 업로드한 파일마다 항목이 하나씩 든 배열을 출력합니다. 실패한 업로드는 빠지므로(stderr에 표시됨) 종료 코드도 함께 확인하세요.
aktar upload photo.jpg --json
[
{
"id": "0B6C2F8E-3D1A-4C55-9E2B-7A41D0C3E9F1",
"filename": "photo.jpg",
"objectKey": "2026/10/7f3c2a91.jpg",
"url": "https://files.example.com/2026/10/7f3c2a91.jpg",
"shortUrl": null,
"destinationId": "5D1A9C3E-7B2F-4E61-8A0D-3C9B6F2E1A47",
"destinationName": "Screenshots",
"mimeType": "image/jpeg",
"size": 482113,
"createdAt": "2026-10-01T12:00:00Z",
"expiresAt": null,
"formats": {
"url": "https://files.example.com/2026/10/7f3c2a91.jpg",
"markdown": "",
"html": "<img src=\"https://files.example.com/2026/10/7f3c2a91.jpg\" alt=\"\">",
"custom": ""
},
"reused": false
}
]| 필드 | 의미 |
|---|---|
id | Aktar 기록에서의 업로드 ID입니다. aktar qr에 넘길 수 있습니다. |
filename | Aktar가 알고 있는 파일 이름입니다. 원래 파일 이름이거나 --name으로 지정한 이름입니다. |
objectKey | 버킷 안에서 파일의 위치입니다. |
url | 링크입니다. |
shortUrl | 짧은 링크. 없으면 null입니다. formats는 이미 이 링크를 사용합니다. |
destinationId | 대상의 ID입니다. |
destinationName | 대상의 이름입니다. |
mimeType | Aktar가 변환한 경우 변환 후의 파일 형식입니다. |
size | 저장된 크기(바이트)입니다. |
createdAt | 업로드된 시각입니다(ISO 8601, UTC). |
expiresAt | 버킷이 파일을 삭제하는 시각이며, 보관되는 파일은 null입니다. |
replacedAt | 파일이 마지막으로 대치된 시각입니다(ISO 8601, UTC). 대치되기 전에는 빠지며, Mac 0.14.0 및 Windows 0.7.0 이전의 Aktar도 이 필드를 넣지 않습니다. |
formats | 네 가지 형식의 링크: url, markdown, html, custom. |
reused | 같은 파일이 이미 있어서 아무것도 업로드하지 않았을 때 true입니다. Mac 0.10.0 및 Windows 0.3.0 이전의 Aktar는 이 필드를 넣지 않습니다. |
shortLinkError | Aktar가 짧은 링크를 만들지 못한 이유. 이때 url은 원래 링크입니다. 문제가 없으면 빠집니다. |
종료 코드
| 코드 | 의미 |
|---|---|
0 | 모두 성공했습니다. |
1 | 업로드나 요청이 하나 이상 실패했습니다. 나머지는 그대로 진행되었습니다. 자동 삭제가 설정되지 않은 경우 같은 Aktar 자체의 오류도 여기에 해당합니다. |
2 | 잘못된 인수, 존재하지 않는 파일, 또는 Aktar에 없는 대상 이름입니다. 아무것도 업로드되지 않았습니다. |
3 | 로그인하지 않았거나, Aktar가 실행 중이 아니거나, 로컬 API가 꺼져 있거나, 토큰이 틀렸거나, 포트에 있는 앱이 Aktar임을 증명하지 못했습니다(또는 증명하기에는 너무 오래된 버전입니다). |
활용 예시
복사하고, 파일 이름만 바꾸면 끝입니다. 모든 예시는 위에 설명한 기능만 사용합니다.
링크를 변수에 저장하기
표준 출력에는 링크만 나오므로 명령어 치환으로 정확히 URL만 받을 수 있습니다. 업로드가 실패하면 || exit 1이 스크립트를 멈춥니다.
url=$(aktar upload build/report.pdf) || exit 1
echo "Report: $url"
Report: https://files.example.com/2026/10/0e7d51b3.pdf빌드를 업로드하고 링크 보내기
빌드를 zip으로 묶어 Builds라는 대상에 커밋의 짧은 해시 이름으로 업로드하고, JSON을 받는 웹훅(채팅 채널, 이슈 트래커, 직접 만든 엔드포인트 등)으로 링크를 보냅니다. 업로드가 실패하면 set -e가 전송 전에 멈춥니다.
#!/bin/sh
set -e
zip -qr app.zip dist
url=$(aktar upload app.zip -d Builds --name "app-$(git rev-parse --short HEAD)")
curl -fsS -X POST "$WEBHOOK_URL" \
-H 'Content-Type: application/json' \
-d "{\"text\": \"New build: $url\"}"Makefile 타깃
make share는 보고서를 오늘 날짜 이름으로 업로드하고 링크를 .last-link에 저장합니다. Makefile에서는 $$가 셸에 $를 넘기며, 명령 줄은 탭으로 시작해야 합니다.
Typora 이미지 업로더
Typora에서 Settings > Image를 열고 이미지 업로더로 Custom Command를 선택한 다음, aktar의 전체 경로(which aktar가 출력하는 경로)와 그 뒤에 upload를 입력합니다. Typora가 이미지 경로를 넘기고, 한 줄에 하나씩 링크를 읽어 갑니다.
/opt/homebrew/bin/aktar uploadWhen Insert… 설정까지 포함한 단계별 안내: Typora 이미지를 S3에 업로드하기.
Finder나 단축어에서 업로드하기
Mac에서 단축어나, Finder에서 파일을 받는 Automator 빠른 동작에 Run Shell Script(셸 스크립트 실행) 동작을 추가하고, 입력을 as arguments(인수로) 전달하도록 설정합니다. 단축어와 Automator는 셸의 PATH를 불러오지 않으므로 첫 줄이 필요합니다. 파일을 선택하고 실행하면 링크가 클립보드에 복사됩니다.
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
aktar upload "$@" | pbcopy
osascript -e 'display notification "Link copied" with title "aktar"'폴더가 아닌 파일만 업로드합니다. 파일이 여러 개면 링크도 한 줄에 하나씩 여러 개가 나옵니다.
임시 파일
로그, 화면 녹화처럼 계속 남겨 둘 필요가 없는 파일은 버킷이 삭제하게 하세요. 먼저 대상에 Aktar의 자동 삭제 규칙이 있어야 합니다. Aktar 메뉴 막대나 대상 설정의 보관 기간에서 한 번만 설정하면 됩니다.
aktar upload crash.log --expires 1
aktar upload screen-recording.mov --expires 7 --qr만료되는 파일은 버킷의 tmp/1d/, tmp/7d/ 등에 저장되며, Aktar가 실행 중이 아니어도 버킷이 삭제합니다.
휴대폰에서 링크 열기
--qr을 쓰면 링크 아래에 QR 코드가 출력됩니다. 휴대폰 카메라를 터미널에 비추세요. 나중에 다시 보려면 업로드 ID를 aktar qr에 넘기면 됩니다. 여기서는 “demo”와 일치하는 최신 업로드입니다.
aktar upload demo.mp4 --qr
aktar qr "$(aktar history demo -n 1 --json | jq -r '.[0].id')"Windows PowerShell
PowerShell에서도 똑같이 동작합니다. $LASTEXITCODE에 종료 코드가 담기고, ConvertFrom-Json으로 --json 출력을 읽을 수 있습니다.
Claude Desktop, Cursor, VS Code에서 쓰는 Aktar
MCP 서버를 JSON 설정으로 받는 앱(Claude Desktop, Cursor, Windsurf 등)에는 이 항목이 필요합니다. VS Code는 .vscode/mcp.json의 servers 아래에 같은 항목을 사용합니다. 그런 다음 에이전트에게 파일을 업로드하거나, 지난주 스크린샷을 찾거나, 임시 링크를 만들어 달라고 요청해 보세요.
앱이 aktar를 찾지 못하면 전체 경로(which aktar)를 사용하거나, npx와 인수 ["-y", "@getaktar/cli", "mcp", "--root", "/Users/you/Projects"]를 사용하세요. --root 뒤에는 에이전트가 업로드할 수 있는 폴더를 넣으세요(Windows에서는 C:\\Users\\you\\Projects처럼).
Aktar가 대신 해 주는 일
CLI는 파일을 넘기기만 하고, 나머지는 Aktar가 각 대상의 설정대로 처리합니다. 그래서 앱에서 설정한 모든 것이 별도 옵션 없이 aktar upload에도 그대로 적용되며, 받는 링크는 실제로 저장된 파일의 링크입니다.
-
경로 템플릿
대상의 객체 경로가
{year},{uuid},{filename}등으로 파일 이름을 정합니다.{md5}와{sha256}은 파일 내용으로 이름을 붙입니다. -
이미지 처리
대상이 이미지를 WebP나 AVIF로 변환하거나 압축, 크기 조절을 한다면 CLI로 올린 파일에도 똑같이 적용되고, 링크는 변환된 파일을 가리킵니다.
-
사진 메타데이터
대상의 업로드 기본값에 있는 이미지 메타데이터 설정으로, 사진이 컴퓨터를 떠나기 전에 위치 정보나 모든 메타데이터를 제거합니다.
-
같은 파일, 같은 링크
중복 파일에 링크 재사용을 켜 두면, 같은 대상에 내용이 같은 파일을 올릴 때 다시 업로드하지 않고 기존 링크를 돌려줍니다.
aktar는 이를 stderr에 알립니다. -
대용량 파일
큰 파일은 5GB 제한 없이 여러 부분으로 나눠 올라가고, 연결이 끊기면 다시 시도해 멈춘 곳부터 이어서 올립니다.
aktar는 파일을 Aktar로 스트리밍하므로 메모리에 통째로 올리지 않습니다. -
공개 링크 또는 임시 링크
링크가 공개 링크인지, 비공개 버킷에서도 동작하는 임시(presigned) 링크인지는 앱에서와 마찬가지로 대상 설정에 따릅니다.
중복 파일 링크 재사용, 이미지 처리, {md5}와 {sha256}, 분할 업로드는 Aktar for Mac 0.10.0과 Windows 0.3.0에서 추가되었습니다: 0.10.0의 새로운 기능.
문제 해결
aktar의 오류 메시지는 aktar:로 시작하며 stderr로 출력됩니다. 종료 코드를 보면 어떤 종류의 문제인지 알 수 있습니다.
Aktar isn't running, or its local API is turned off
Aktar를 열고 설정 > 연동에서 로컬 연결 허용이 켜져 있는지 확인하세요. 그곳에서 포트를 바꿨다면 --port나 AKTAR_PORT로 넘기거나, aktar login --port를 다시 실행하세요. 종료 코드 3.
Not connected to Aktar yet
저장된 토큰도 없고 AKTAR_TOKEN도 없습니다. Aktar의 설정 > 연동에 있는 토큰으로 aktar login을 실행하세요. 종료 코드 3.
The token doesn't match Aktar's anymore
Aktar에서 토큰을 다시 생성했거나 잘못 입력했습니다. 현재 토큰으로 aktar login을 다시 실행하세요. AKTAR_TOKEN이 설정되어 있으면 저장된 토큰보다 우선하므로, 이 값도 업데이트하거나 해제하세요. 종료 코드 3.
The app on port … couldn't prove it's Aktar
Aktar의 포트에서 무언가가 응답했지만 내 토큰을 가지고 있음을 보여 주지 못해 토큰을 보내지 않았습니다. Aktar가 실행 중이라면 토큰이 바뀌었을 가능성이 높으니 aktar login을 다시 실행하세요. Aktar가 실행 중이 아니라면 Aktar를 여세요. 종료 코드 3.
This version of Aktar can't prove it's Aktar
aktar 0.6.0 이상은 토큰을 보내기 전에 앱을 확인하며, 이를 위해 Aktar for Mac 0.18.0 또는 Aktar for Windows 0.11.0 이상이 필요합니다. Aktar를 업데이트하면(Aktar가 직접 업데이트를 안내합니다) 명령이 다시 작동합니다. 종료 코드 3.
MCP: This server doesn't upload local files
에이전트가 홈 폴더나 디스크 최상위에서 aktar mcp를 시작했고 --root가 없습니다. 서버의 명령이나 설정에 파일을 가져올 폴더와 함께 --root를 추가하고(예: aktar mcp --root ~/Projects) 에이전트를 다시 시작하세요.
Auto-delete isn't set up for this destination
--expires를 쓰려면 버킷에 자동 삭제 규칙이 있어야 합니다. Aktar 메뉴 막대나 대상 설정의 보관 기간에서 한 번만 설정하거나, --expires 없이 업로드하세요. 종료 코드 1.
No destination named "…"
메시지에 Aktar에 있는 대상 이름이 나열됩니다. 철자를 확인하고, 공백이 있는 이름은 따옴표로 감싸거나(-d "Client work") aktar destinations에 나오는 ID를 쓰세요. 종료 코드 2.
큰 파일 업로드가 오래 걸려요
스토리지 제공업체의 속도 때문입니다. aktar는 업로드에 시간 제한이 없으며, 터미널에서는 stderr에 진행 상황을 보여 줍니다. 끝날 때까지 Aktar를 실행해 두세요. 연결이 끊기거나 Aktar가 종료되면(Aktar closed the connection before the request finished) 같은 파일을 다시 업로드하세요. Aktar for Mac 0.10.0과 Windows 0.3.0부터는 마지막 부분부터 이어서 올립니다.
aktar가 시작되지 않아요: SyntaxError 또는 parseArgs
Node.js 버전이 18보다 낮습니다. node --version으로 확인하고 업데이트하거나, 자체 Node.js를 함께 설치하는 Homebrew로 aktar를 설치하세요.
PowerShell에서 스크립트 실행이 비활성화되어 있다고 나와요
PowerShell 실행 정책이 npm이 aktar용으로 설치한 스크립트를 막고 있습니다. 대신 aktar.cmd를 실행하거나, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned로 로컬 스크립트를 한 번 허용하세요.
