Metadata-Version: 2.4
Name: scriptvault
Version: 0.2.1b0
Summary: Store and run project commands in a hidden vault directory
Author: Majwt
License-Expression: MIT
Project-URL: Homepage, https://github.com/Majwt/ScriptVault
Project-URL: Repository, https://github.com/Majwt/ScriptVault
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# ScriptVault (`sv`)

Store and run project commands in a hidden vault directory.

`sv` keeps scripts, orchestrations, and environment files under a hidden `.sv/` directory so projects do not need a pile of top-level Makefile targets, shell scripts, or ad-hoc commands.

## Install

Requires Python 3.11+.

From PyPI:

```sh
pipx install scriptvault
```

From a checkout:

```sh
pipx install --editable .
```

## Quick start

Initialize a vault in a project directory:

```sh
sv init
```

Create a script:

```sh
sv add hello
```

Run it:

```sh
sv hello
# or
sv run hello
```

List targets:

```sh
sv list
```

## Vault layout

```text
.project/
  .sv/
    vault.toml
    .env
    scripts/
      hello.sh
      hello.env
  includes/
    c-hello/
      .sv/
        vault.toml
        scripts/
          build.sh
```

- `vault.toml` defines inline scripts, orchestrations, and nested vault includes.
- `.env` is the global dotenv file.
- `scripts/*.sh` are executable file scripts.
- `scripts/NAME.env` is the per-script dotenv file.
- `[include.NAME]` sections load scripts from nested vaults (see below).

### Nested Vaults

Include scripts from subdirectories:

```toml
[vault]
name = "myproject"

[include.c-hello]
path = "includes/c-hello/.sv/vault.toml"

[include.shell]
path = "includes/shell/.sv/vault.toml"
```

Run scripts with the include name prefix:

```bash
sv run c-hello build
sv c-hello build
```

Implied run (`sv deploy`) only works for root vault scripts.

## Scripts

### File scripts

A file at `.sv/scripts/hello.sh` becomes `sv hello`.

```sh
#!/bin/sh
echo "Hello from $SV_NAME"
```

### Inline scripts

Define a command in `vault.toml`:

```toml
[scripts.hello]
cmd = "echo hello"
```

### Creating scripts

```sh
sv add hello
sv add hello --in < script.sh
```

## Running targets

```sh
sv hello
sv run hello arg1 arg2
sv run hello -- --special-arg
```

Arguments after the target are passed to the script. Use `--` to pass a leading dash safely.

## Orchestrations

An orchestration is a named sequence of steps in `vault.toml`.

```toml
[orchestrate.ci]
steps = [
  { sh = "echo build" },
  { run = "hello" },
  { parallel = ["test", "lint"] },
]
```

Run it like any other target:

```sh
sv ci
```

Orchestrations can call scripts and other orchestrations. `sv` detects cycles and reports them.

## Environment

Environment files are dotenv-style `KEY=VALUE` files.

Precedence, from lowest to highest:

1. `.sv/.env`
2. `.sv/scripts/NAME.env`
3. The real environment
4. Injected `SV_*` variables

Injected variables:

- `SV_ROOT`: project root
- `SV_DIR`: `.sv` directory
- `SV_CWD`: current working directory at invocation
- `SV_NAME`: target name, when running a named script

## Editing

Open the interactive target picker:

```sh
sv edit
```

`sv edit` uses `fzf` when available and stdin/stdout are a TTY; otherwise it falls back to a numbered prompt.

Edit a specific target:

```sh
sv edit hello
```

Edit a script's environment:

```sh
sv edit hello env
```

Edit a target's configuration in `vault.toml`:

```sh
sv edit hello config
```

Edit the global vault config or global env:

```sh
sv edit config
sv edit env
```

## Shell completion

Print a completion script for your shell:

```sh
sv completion bash
sv completion zsh
sv completion fish
```

Examples:

```sh
# bash
eval "$(sv completion bash)"
```

```sh
# zsh
eval "$(sv completion zsh)"
```

```sh
# fish
sv completion fish | source
```

## Help

```sh
sv help
sv --version
```

## Documentation

For detailed guides and documentation:

- [Vault Activation](docs/VAULT_ACTIVATION.md) - How to activate specific vaults
- [Nested Vaults](docs/IMPLEMENTATION_SUMMARY.md) - Working with nested vaults
- [Completion Guide](docs/COMPLETION_REPORT.md) - Shell completion details

---

## Root Vault Activation

When running `sv` from any subdirectory, it automatically uses the root `.sv` directory.

See [Vault Activation](docs/VAULT_ACTIVATION.md) for detailed information.

## Orchestration with Nested Scripts

Orchestrations can reference scripts from included vaults.

See [Nested Vaults](docs/IMPLEMENTATION_SUMMARY.md) for examples.

## Shell Completion

Generate shell completion scripts:

```bash
# Auto-detect from SHELL environment variable
sv completion $shell | source

# Specify shell explicitly
sv completion bash | source
sv completion zsh | source
sv completion fish | source

# Use full path
sv completion /usr/bin/bash | source
```

See [Shell Completion](docs/COMPLETION_REPORT.md) for details.
