nimbus-cli 0.2.1

Run one command or open an interactive REPL to manage and sync objects in vaults. A vault is a filesystem-like tree that stores metadata plus a way to reach the object, so one can be backed by an API, your own filesystem, a shell command, or another vault.
nimbus-cli-0.2.1 is not a library.

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).

nimbus-cli ls              # one command, then exit
nimbus-cli cd docs         # the session is saved, so the next invocation starts here
nimbus-cli --help          # clap's help, as usual
nimbus-cli                 # no arguments: the REPL

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

cargo install nimbus-cli          # from crates.io
cargo install --path crates/cli   # or from a checkout of the workspace

Configuration

CLI settings (~/.config/.nimbus/cli_config.toml)

default_local_vault = true       # auto-register the local filesystem as a vault
local_vault_path = "/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_cmd must print JSON on stdout matching the object schema — serde's externally-tagged enum, i.e. {"Leaf": {"name": ..., "id": ..., "meta": {...}}} or {"Branch": {..., "children": null}}.
  • fetch_cmd streams raw content bytes to stdout.
  • send_cmd reads the payload from stdin.
  • put_cmd/delete_cmd just need to succeed (exit code 0); stderr is captured for error reporting on failure.

Notes

  • ls always 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.
  • mv and push/pull's local↔remote transfers only proceed with the destructive step (delete, in mv'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.