smb2-cli
A command-line SMB2/3 client. It talks to a share directly over the network, so you never mount it: no root, no mount_smbfs, no kernel client. One binary and a target like //host/share/path.
Built on the smb2 crate, which does all the protocol work. Both live in the
same repo, so a protocol fix and the CLI change that uses it ship together.
Why
A mounted share is fine until you have thousands of small metadata operations. macOS smbfs does one synchronous round trip per syscall with no overlap, so a bulk delete crawls. smb2-cli opens N independent connections and spreads the batch across them.
Measured against a Raspberry Pi over LAN, 500-path batches, each arm getting its own disjoint slice:
| Operation | Mounted share | smb2 at -j 16 |
|---|---|---|
| Delete files | 34/s | 500/s |
| Remove empty directories | 3.3/s | 155/s |
For reference, one SSH process doing plain local syscalls on the Pi managed 556/s on the deletes. So the CLI beats going through the mount, and it beats shelling into the box. On a longer run (39,176 files) it sustained 877/s.
-j 16 was the sweet spot on that four-core Pi. -j 32 was slower, so don't crank it past what the server can serve.
benchmarks/cli-bulk-ops/bulk-bench.sh in the repo reproduces all of this.
Every command also prints JSON, which makes it pleasant to drive from a script or an agent.
Install
The binary is called smb2.
Credentials
In order of preference:
--password-commandruns a command and reads its stdout:--password-command 'secret RASPI_SMB_PASSWORD'. Keeps the password out of your shell history and out ofps.SMB2_PASS, usually from a.envfile or a secrets manager.- A prompt, when you're on a terminal and gave none of the above.
There's also --password, but your shell will remember it and so will the process list. Avoid it.
--user (or SMB2_USER) sets the username; --guest connects with no credentials.
Commands
# Look around
# Move bytes
# Change things
realpath prints the path the way the server stores it: its casing, and long names in place of 8.3 aliases like PROGRA~1. It needs SMB 3.1.1 (Samba, or Windows 10 / Server v1803 and later) and says so when the server can't answer.
mkdir -p is happy to find the directory already there, and stops when the name belongs to a file, the way GNU mkdir -p does.
put picks its destination the way cp does. A target that ends in /, or that's already a directory on the share, gets the file inside it under its own name; anything else is the full path to write. An upload never replaces a directory: if the destination is one, put says so and stops.
Transfers stream in both directions, so size isn't a limit and neither is your memory: a 600 MB get runs in about 60 MB of RAM, and put is the same the other way.
--json works on every command. --dry-run works on everything that writes (mkdir, rm, rmdir, mv, put, and get): it prints what would happen and makes no connection at all.
Batches
Every path-taking command accepts --from-file, where each line is a path relative to the target you give. Use - to read from stdin. mv --from-file takes from<TAB>to pairs.
# Delete 5,000 empty directories over 16 connections
# Rename in bulk
|
-j sets how many connections to spread the work over (default 8). It goes after the subcommand, and only the commands that actually spread work take it: stat, mkdir, rm, rmdir, and mv. Everything in one batch has to live on the same host and share.
Exit codes
0 when everything worked, 1 when anything failed.
A batch doesn't abandon the run on the first bad path. It processes the rest, reports the per-path failures on stderr, and exits non-zero. So you always find out, and you never have to guess how far it got.
License
MIT or Apache-2.0, your choice.