myboxctl

한국어

myboxctl is a small, predictable CLI for managing files through the NAVER MYBOX Open API. It is built for AI-agent subprocesses and remains readable for direct terminal use. It is not a sync tool, SDK, MCP server, or complete API wrapper.

I built it for my own Hermes Agent and Codex CLI workflows. This is an independent project and is not affiliated with NAVER.

Commands

Command	Purpose
list / ls	List a folder or show one resource
info	Show file or folder metadata
mkdir	Create a remote folder; supports -p
upload	Upload a file or an explicit recursive folder tree
download	Download a file or an explicit recursive folder tree
delete	Move a remote file or folder to the MYBOX trash
rename	Rename a file or folder in place
move	Move a file or folder into an existing folder

Install

Requires Node.js 20 or later.

npm install -g @oliverne/myboxctl
myboxctl --version

Set a MYBOX PAT through MYBOX_PAT, or store one token line in ~/.config/myboxctl/credentials with file mode 600. Never pass a PAT as a CLI argument or put it in source code, logs, or Git.

Quick start

Remote paths are absolute POSIX paths beginning with /.

myboxctl list /agents
myboxctl info /agents/report.md
myboxctl mkdir -p /agents/output
myboxctl upload ./report.md /agents/output/ --mkdir
myboxctl download /agents/output/report.md ./report.md
myboxctl upload ./reports /agents/ --recursive --mkdir
myboxctl upload ./reports /agents/ --recursive --checkpoint ./reports.upload.json
myboxctl upload ./reports /agents/ --recursive --resume ./reports.upload.json
myboxctl download /agents/reports ./reports-copy --recursive
myboxctl delete /agents/output/report.md
myboxctl rename /agents/output/draft.md final.md
myboxctl move /agents/output/final.md /agents/archive/

Paths containing spaces must be quoted so that the shell passes each path as one argument. The quotes are shell syntax and are not part of the local or remote file name.

PowerShell accepts single or double quotes:

myboxctl download '/Team Files/big report.zip' '.\Local Files\big report.zip'

Use double quotes in Command Prompt (cmd.exe):

myboxctl download "/Team Files/big report.zip" ".\Local Files\big report.zip"

Important behavior:

• upload compares size and modification time, not content hashes. It skips matching files and rejects a clearly newer remote file; use --force only for an intentional overwrite.
• download preserves an existing local file unless --overwrite is explicit.
• Folder transfer requires --recursive, never merges an existing destination tree, and rejects symlinks and names that are not portable across macOS, Linux, and Windows. It excludes macOS AppleDouble metadata files whose names start with ._.
• --checkpoint <file> records recursive upload progress in an exclusive local JSON file and --resume <file> re-verifies the saved manifest and remote root before skipping only the checkpoint-owned completed entries. A failed run keeps the checkpoint and reports resumeCheckpointPath; a successful run removes it. An uncertain in-flight mutation fails closed with RESUME_UNCERTAIN instead of repeating a POST.
• delete moves resources to the MYBOX trash. Root, encrypted folders, and shared-with-me folders are unsupported.
• rename and move keep the resource ID, call exactly one mutation endpoint, and fail before mutating when the new name collides with another resource in the destination. move requires an existing destination folder, rejects a folder moving into itself or its descendant, and never renames.
• New remote resources are created with NFC names. Existing lookups use the given spelling, and ambiguous Unicode-equivalent candidates fail safely. rename sends the requested name as-is.

Automation

Use --json and check the exit code first. Stdout contains one schemaVersion: 1 JSON result. With --verbose, safe progress events are written as JSON Lines to stderr. PATs and signed transfer URLs are redacted.

myboxctl upload ./report.md /agents/output/ --mkdir --json

Set MYBOX_PLAN to 30GB, 80GB, 180GB, 330GB, 2TB, 5TB, 10TB, or 20TB to apply the documented plan-specific local limits and download daily-limit advisory. A {"plan":"180GB"} value in ~/.config/myboxctl/config.json is used when the environment variable is absent. The plan is declared by the user; it cannot be detected safely from storage capacity.

For an opt-in support log, add --diagnostic-log <new-file>. The file is created exclusively and contains JSONL events and the final result, but it may contain local paths and a redacted stack; review it before sharing. Existing files are never overwritten.

Set {"diagnostics":{"onError":true}} in the same config file to keep a redacted JSONL log only for failed runs. Automatic logs are written under $XDG_STATE_HOME/myboxctl/diagnostics/ (or ~/.local/state/myboxctl/diagnostics/), keep the newest 20, and their path appears on stderr or as the diagnosticLogPath field of a JSON failure. Successful runs create no file.

Exit	Meaning
0	Success
2–5	Input, auth, missing, conflict
6–8	API, local I/O, rate limit
70	Unexpected internal error

See the versioned CLI contract for exact JSON fields, actions, options, and exit-code semantics.

Agent Skill

The repository includes a reusable Agent Skill with CLI installation, command examples, and the essential safety rules. Copy the entire skill directory to your agent's skill location; for Hermes user skills, use ~/.hermes/skills/myboxctl/.

Development

Source development requires Bun 1.4 or later.

bun install --frozen-lockfile
bun run check
bun run build

Live MYBOX tests are opt-in and mutate only an isolated test prefix.

MYBOX_PAT=<YOUR_PAT> bun run test:integration

Documentation

• CLI contract
• NAVER MYBOX Open API

License

MIT