cd2

cd2 is a Node.js CLI and Agent Skill for basic CloudDrive2 file operations over gRPC.

The npm package is @andie/cd2; the executable command is cd2.

Install And Run

npx @andie/cd2 --help

For local development:

pnpm install
pnpm cd2 -- --help

Configure

npx @andie/cd2 config set endpoint localhost:19798
npx @andie/cd2 config set token <api-token>
npx @andie/cd2 config get

Config is stored at ~/.config/cd2/config.json unless XDG_CONFIG_HOME is set.

Precedence:

1. CLI flags
2. Environment variables
3. User config

Environment variables:

CD2_ENDPOINT=localhost:19798
CD2_API_TOKEN=<api-token>

Commands

npx @andie/cd2 stat /docs/a.txt
npx @andie/cd2 ls /docs --refresh
npx @andie/cd2 tree /docs --max-depth 3 --limit 300
npx @andie/cd2 find /docs --name invoice --max-depth 8 --limit 200
npx @andie/cd2 find /docs --glob "*.pdf" --type file
npx @andie/cd2 mkdir /docs/new-folder
npx @andie/cd2 upload ./a.txt /docs/a.txt
npx @andie/cd2 download /docs/a.txt ./a.txt
npx @andie/cd2 rename /docs/a.txt b.txt
npx @andie/cd2 mv /docs/b.txt /archive --conflict skip
npx @andie/cd2 cp /archive/b.txt /docs --conflict rename
npx @andie/cd2 rm /docs/b.txt

Remote paths must be absolute and begin with /.

upload and download take full file paths. mv and cp take destination directories. Use rename to change a file name.

rename takes a single new name, not a path. Use mv to move a file to another directory.

rm uses normal CloudDrive2 deletion by default. Use --permanent only when permanent deletion is explicitly desired.

tree and find use bounded recursive listing. If --max-depth or --limit is omitted, the command applies defaults and reports the effective values in data.limits. Check data.truncated and data.truncation.byLimit / data.truncation.byMaxDepth before treating the result as complete.

find filters names locally from recursive listings; it does not use CloudDrive2 native search.

Output

Commands write stable JSON Agent Results to stdout:

{
  "ok": true,
  "command": "stat",
  "data": {}
}

Diagnostics and progress go to stderr.

Mutation commands return an operation receipt. Prefer these fields over raw CloudDrive2 RPC fields:

{
  "ok": true,
  "command": "cp",
  "data": {
    "from": "/archive/a.txt",
    "to": "/docs/a.txt",
    "destDir": "/docs",
    "conflict": "rename",
    "reportedPaths": [],
    "warnings": [
      {
        "code": "RESULT_PATH_NOT_REPORTED",
        "message": "CloudDrive2 did not report the final path."
      }
    ]
  }
}

For cp, mv, and rename, to is the requested target path. If CloudDrive2 reports affected paths, they appear in reportedPaths; this array can be empty even when the command succeeds. rm returns removed: true after successful deletion.

Development

pnpm test
pnpm typecheck
pnpm build

The normal test suite does not require live CloudDrive2 credentials.

Optional live smoke test:

CD2_ENDPOINT=localhost:19798 \
CD2_API_TOKEN=<api-token> \
CD2_LIVE_ROOT=/ \
pnpm live:smoke

Use a dedicated API token scoped to a disposable test root. If CloudDrive2 token RootDirectoryRequired is set, that root appears to the CLI as /.