nimbus-cli
An interactive shell for managing vaults — commands to navigate, transfer, and sync objects across any configured origin (local filesystem, HTTP API, another vault, or a custom shell command).
A vault is a logical tree of objects (folders and files, conceptually) backed by a pluggable origin — the actual backend the data lives in. This CLI is a thin frontend over nimbus-core (which owns the App/session state) and nimbus-vault (which implements the vault/origin model and does the actual work).
nimbus-tui (cargo install nimbus-tui) is the other frontend over the same App: a ranger-style file manager, which shows a whole vault at once where this shows one command's worth. It's the easier one to start from; this one is where scripting and one-shot commands live.
How it works
nimbus-cli runs either way round: pass a command and it runs that one command and exits, pass nothing and it opens a rustyline-backed REPL (tab completion for subcommand names and cd's argument).
Both modes drive the same App and the same session file, so you can mix them freely. A one-shot command that fails exits 1 with Error: … on stderr; a mistyped one gets clap's usage message and its exit code, rather than silently opening the REPL. The REPL's prompt carries your position — nimbus />> at the root, nimbus my-vault/docs>> inside a vault; the examples below write it as nimbus> for brevity.
There's always a special local vault (named LOCAL) representing your own filesystem — every put/get moves data between that local vault and whichever remote vault you're working with. You never touch the OS filesystem directly; put/get's local-side paths are checked to stay under the configured local root.
Installation
Configuration
CLI settings (~/.config/.nimbus/cli_config.toml)
= true # auto-register the local filesystem as a vault
= "/home/you" # optional; defaults to $HOME
Set default_local_vault = false if you don't want the CLI touching your filesystem at all — put/get will then require every source/destination to be an explicit remote vault (LOCAL won't be registered).
Vault definitions
Each vault you register (other than the automatic LOCAL one) is defined by its own .toml file — see crates/vault/README.md for the full origin_config shape (fs, http, command, vault), including [origin_config.auth] for an http origin that needs credentials (a nimbus-daemon, typically — keep the token in an environment variable, not in the config file). Register one with:
nimbus> new /path/to/vault.toml
or launch the interactive wizard (built on nimbus-creator) by running new with no path — it prompts for a name, root id, origin type, and that origin's fields, then writes and registers the resulting vault.toml. The wizard defaults to saving under ~/.config/.nimbus/vaults/<name>.toml, so vaults you create stay together and can be found again; the path is editable, and it refuses to overwrite an existing config.
Registering a name that's already taken by a different config is refused, since replacing it would leave the original vault unreachable. Use forget <vault> to free the name first. Re-registering the same config path is fine — that's how an edit to a config file gets picked up.
Session model
Three things are persisted to ~/.local/state/nimbus/session.toml: the registry of vaults (name → config path), the vault you had selected, and the directory you were in. They're written on new, on forget, and on the way out — whether you typed exit, hit Ctrl-C/Ctrl-D, or ran a single command.
That's what makes the one-shot mode usable rather than a novelty:
$ nimbus-cli cd my-vault/docs
$ nimbus-cli ls # lists my-vault/docs, not the vault list
$ nimbus-cli cd # no argument: back to the root, deselecting the vault
Restoring the directory has to reach the origin (resolving a path to an ObjectId means walking it, one list per component), so it happens in an explicit App::restore_session() after App::init() rather than inside it. It degrades instead of failing: a vault that's gone drops you at the root, and a directory that's gone drops you at that vault's root, each with a warning on stderr.
One consequence worth knowing: since you start off inside a vault, the cd <vault>/<path> shorthand only applies at the root. Standing in a vault, cd docs is a path in that vault. cd with no argument gets you back out.
A vault whose config can't be opened right now — say its [origin_config.auth] reads a token_env you haven't exported in this shell — is reported, skipped for the session, and stays registered. It'll be back as soon as its config builds again; only forget unregisters a vault.
Commands
Inside the REPL, type a subcommand name:
Navigation
ls # list contents of the current directory, or all registered vaults if none selected
vaults # list all registered vaults
select <vault> # make <vault> the current vault
cd <path> # change directory inside the current vault
cd <vault>/<path> # select a vault and navigate in one step (when no vault is selected yet)
cd # (no argument) return to the root — deselects the current vault
Registering vaults
new <config.toml> # register a new vault from its config file
new # launch the interactive wizard to build and register one
forget <vault> # stop tracking a vault; its config file and data are left alone
# (`LOCAL` can't be forgotten — turn off default_local_vault instead)
Moving data
put <path> [vault] [dest]
get <path> [vault] [dest]
put uploads something from your local filesystem into a vault. get downloads something from a vault into your local filesystem. vault defaults to whichever vault is currently selected. Arguments are positional.
dest defaults to your current position in the vault for put, and to the local vault's root for get — not the shell's working directory, which is outside the local root nearly all the time and so would just fail.
Operating within a vault
mkdir <path> [vault] # create a directory
touch <path> [vault] # create an empty file
rename <path> <new-name> [vault] # rename in place; takes a name, not a path
cp <path> <destination> [vault]
mv <path> <destination> [vault]
delete <path> [vault] [-f | --force]
delete refuses to remove a non-empty directory unless --force is given. mkdir/touch refuse to clobber anything already at the path — touch is therefore not the usual "create or bump the timestamp", since an origin's put truncates.
rename takes a bare name, not a path; use mv to relocate. It is implemented as a copy under the new name followed by deleting the original, because no origin has a rename primitive — correct everywhere, but it costs a full data copy, which is worth knowing for a large object on a remote origin.
Paths
Every path argument above is a vault:path spec:
| Spec | Means |
|---|---|
notes.txt |
relative to the current directory |
/docs/notes.txt |
absolute within the current vault |
backup:/inbox |
the vault named backup, from its root |
A vault: prefix is what distinguishes a vault from a directory of the same name — docs is always a path, docs: is always the vault. The prefix is only recognised when it names a registered vault, so an object whose name contains a colon still resolves as a path.
That prefix is also how cp/mv cross vaults, including between different origin types:
nimbus> cp notes.txt backup:/inbox # into a directory, keeping the name
nimbus> cp notes.txt backup:/inbox/copy.txt # under a new name
nimbus> mv docs archive:/2026 # directories move recursively
The destination may be an existing directory (the object keeps its name) or a path that doesn't exist yet (it lands under that new name). An existing file as the destination is refused rather than overwritten.
Syncing with a remote origin
push [vault] # send local changes to the vault's origin
pull [vault] # bring changes from the origin into the vault
push/pull recursively sync an entire subtree, skipping objects that haven't changed (compared by metadata) rather than re-transferring everything on every run.
Exiting
exit # save session state and quit
Ctrl-C/Ctrl-D also exit the REPL.
Writing a custom origin
If none of the built-in origins (fs, http, vault) fit your backend, command lets you wire up arbitrary shell commands. Each operation gets its own command template with {id}, {name}, {size}, {content_type}, {modified}, {kind} (leaf/branch) and {destination} (where applicable) substituted in, plus any custom extras you define — see crates/vault/README.md for the full reference:
list_cmd/get_cmdmust print JSON on stdout matching the object schema — serde's externally-tagged enum, i.e.{"Leaf": {"name": ..., "id": ..., "meta": {...}}}or{"Branch": {..., "children": null}}.fetch_cmdstreams raw content bytes to stdout.send_cmdreads the payload from stdin.put_cmd/delete_cmdjust need to succeed (exit code 0); stderr is captured for error reporting on failure.
Notes
lsalways reflects the true current state of a vault's origin — it's never served from cache.- Content (file bytes) is streamed, not buffered — large files don't get fully loaded into memory during transfer.
mvandpush/pull's local↔remote transfers only proceed with the destructive step (delete, inmv's case) after the copy has succeeded.- Tab completion currently covers subcommand names and
cd's first argument only; other commands' path arguments aren't completed yet. It's a REPL feature — in one-shot mode your shell's completion is what's running. - To script several commands in one process, pipe them into the REPL (
printf 'select v\nls\n' | nimbus-cli). One command per invocation is the other option, and the session file is what carries state between them.
Testing against other origins
test/ holds a vault config per origin type (fs, http, command, and a vault wrapping another vault), including reference http and command origin implementations to run them against. Export a scratch XDG_STATE_HOME before you start and your real vault registry is left untouched — see that README for the per-origin walkthrough.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option — the same terms as the rest of the workspace.