llms.txt

# bdc

> A command-line client for Baidu Netdisk (百度网盘): list, search, manage, upload, download, share and save shares. One binary for macOS, Linux and Windows. Built to be driven by AI agents: `--json` output, meaningful exit codes, no prompts without a terminal. Human-readable output is Chinese; the JSON is language-neutral.

## Quick start

1. `bdc who --json`. If `loggedIn` is false, log in: `bdc login --cookies "BDUSS=…; STOKEN=…"` (or `--from-chrome` / `--from-edge`).
2. Inspect: `bdc ls --json <dir>` → `files[]` of `{path, name, fsId, size, isDir, md5?, ctime, mtime}`; `bdc meta --json <path…>`; `bdc tree --json [--depth n] <dir>` → nested `root.children`; `bdc search --json -r --path <dir> <keyword>`.
3. Act: `bdc download --json -o <local dir> <path…>`, `bdc upload --json <local…> <netdisk dir>`, `bdc mkdir`, `bdc rm`, `bdc cp`, `bdc mv`, `bdc share create`, `bdc share save`.
4. Read stdout: check `ok`, then the command's fields. For downloads take each file's absolute local path from `files[].file`; never build it yourself.

## Output

- With `--json` (before or after the command), stdout carries exactly one JSON document; progress and logs go to stderr. Keys are sorted. Times are RFC 3339 with the local offset; sizes are bytes; ids are exact integers.
- Every document has `ok` and `command` (e.g. `"share create"`). On failure: `error: {kind, message, exitCode, code?}`, where `code` is Baidu's error code when there is one (31066 / -9 not found, 31061 / -8 already exists, -12 wrong extraction code). Work finished before a failure is still in the document.
- `--help` and `--version` also answer with a document under `--json` (`help`, `version`).

## Exit codes

| code | error.kind | meaning | what to do |
|---|---|---|---|
| 0 | – | done | read the fields |
| 1 | failed | server, network or transfer failure | retry later |
| 2 | input | not found, already exists, no wildcard match, wrong extraction code, bad value | fix the input; `bdc ls --json` to look around |
| 3 | dependency | a permission problem: browser cookies unreadable, or `update` cannot write to bdc's directory | log in with `--cookies`; for `update`, ask the user to run `sudo bdc update` |
| 4 | auth | not logged in or login expired; with `code` 132, Baidu wants a security check instead | `bdc login` again; for 132 logging in does not help: ask the user to run the same command in a terminal (bdc then asks where to send a code and for the code), or to verify on the web |
| 64 | usage | bad command line, or a confirmation needed without a terminal | see `bdc <command> --help`; add `-y` |
| 130 | cancelled | interrupted | rerun; transfers resume |

## Rules

- Netdisk paths are absolute (`/Photos/a.jpg`) or relative to the working directory set by `bdc cd` (`bdc pwd --json`). Quote them: they contain spaces, Chinese and wildcards.
- Wildcards `*`, `?`, `[…]` work in any path component and are expanded by bdc against what exists; a pattern with no match is an `input` error. A name that exists exactly as written always means itself (`"[1].txt"` is that file), and `\` escapes a wildcard character.
- `md5` is present only when it is the file's real content md5. Baidu does not know it for files stored in several blocks (typically those uploaded in 4 MiB pieces), so those have no `md5`.
- `mkdir` of a directory that already exists succeeds (`existing[]`), so it is safe to repeat.
- `cp`/`mv <src…> <dst>`: if `dst` is an existing directory, sources go into it; otherwise one source is copied/renamed to `dst`, several go into a new directory `dst`. `items[]` lists each `{from, to}`.
- `rm` moves to the recycle bin: `bdc recycle list --json` (`files[].fsId`, `daysLeft`), `bdc recycle restore <fsId…>`, `bdc recycle delete -y <fsId…>` (permanent; Baidu may demand a security check, exit 4 with code 132 without a terminal, see above).
- Downloads: `-o <dir>` (default: the `save-dir` setting). A directory downloads recursively into `<dir>/<its name>/…`; `--full-path` keeps the whole netdisk path. A file already on disk is `{"status": "skipped", "reason": "exists"}`; `--overwrite` replaces it. Interrupted downloads resume (a `.bdc-part` file sits beside the target meanwhile).
- Uploads: the last argument is the netdisk directory; the others are local files or directories (uploaded recursively as `<dir>/<name>/…`). If the target exists: `--policy skip` (default) → `skipped`/`exists`; `overwrite` replaces; `rsync` replaces unless the size is the same (`skipped`/`same-size`). `status: "rapid"` means Baidu already had the content and nothing was sent. Interrupted uploads resume.
- `files[].status` in transfers: `downloaded`, `uploaded`, `rapid`, `skipped` (`reason`: `exists`, `same-size`, `symlink` for a symlinked local directory, which is not followed), `failed` (with `error`); `summary` counts them. A path that cannot be read, or two files that would land on the same target, fail on their own while the rest still transfers. If any file failed the command fails, but the document lists every file.
- Shares: `bdc share create --json [-p <4 chars>] [--days n, 0 = forever] <path…>` → `shareId`, `link`, `pwd`, `url` (link with `?pwd=`). `bdc share save --json "<link>" [<code>] [--to <dir>]` saves someone else's share into the working directory (or `--to`, created if missing); the code may be in the link. Saving the same share again fails with code 4 (already saved). Saving your own share fails (Baidu: 文件已存在, code 2). `bdc share cancel <shareId…>`.
- Offline downloads run on Baidu's servers: `bdc offline add --json --to <dir> <url…>` → `ids`; poll `bdc offline list --json <id…>` (`status` 0 = done, 1 = running).
- `logout`, `recycle delete` and `update` need `-y` without a terminal. `update` fails with `dependency` (exit 3) when bdc's directory is not writable (e.g. installed by the macOS .pkg into /usr/local/bin): ask the user to run `sudo bdc update`. With no command and no terminal, bdc exits 64 instead of opening the shell.

## Command map

```text
Account   login · logout -y · who · users · su <uk|name> · quota
Browse    ls [-l] [--sort name|size|time] [--desc] · tree [--depth n] · meta · search [-r] [--path dir] · cd · pwd
Manage    mkdir · rm · cp · mv · recycle list|restore|delete
Transfer  download [-o dir] [-p conns] [--overwrite] [--full-path] · upload [--policy skip|overwrite|rsync] · offline add|list|cancel|delete
Share     share create|list|cancel|save
Other     config [set …|reset] · update [--check] [-y]
```

Settings and accounts: `config.json` in the user config directory (`bdc config --json` shows the path and the settings, never the cookies), or `$BDC_CONFIG_DIR`.