nimbus-cli 0.2.0

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

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`](https://github.com/PeachGB/nimbus/tree/main/crates/core) (which owns the `App`/session state) and [`nimbus-vault`](https://github.com/PeachGB/nimbus/tree/main/crates/vault) (which implements the vault/origin model and does the actual work).

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

```bash
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

```bash
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`)

```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`](https://github.com/PeachGB/nimbus/blob/main/crates/vault/README.md) for the full `origin_config` shape (`fs`, `http`, `command`, `vault`), including [`[origin_config.auth]`](https://github.com/PeachGB/nimbus/blob/main/crates/vault/README.md#authenticating-an-http-origin) for an `http` origin that needs credentials (a [`nimbus-daemon`](https://github.com/PeachGB/nimbus/blob/main/crates/daemon/README.md), 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`](https://github.com/PeachGB/nimbus/tree/main/crates/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`](https://github.com/PeachGB/nimbus/blob/main/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/`](https://github.com/PeachGB/nimbus/blob/main/crates/cli/test/README.md) 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](https://github.com/PeachGB/nimbus/blob/main/crates/cli/LICENSE-APACHE) or
[MIT license](https://github.com/PeachGB/nimbus/blob/main/crates/cli/LICENSE-MIT) at your option — the same terms as the rest of the workspace.