DOCS.md

# voice — Help

Generated from `voice --help` and `voice <cmd> --help` (v3.1, 14 commands).

## voice --help

```text
usage: voice [-h] [-v] [--non-interactive] [--version]
             [--completion {bash,zsh,fish}]
             {get,cast,delta,graft,chorus,add,list,info,remove,cleanup,auth,report,path,doctor} ...

Lift a model's voice and cast it onto another model.

positional arguments:
  {get,cast,delta,graft,chorus,add,list,info,remove,cleanup,auth,report,path,doctor}
    get                 Get a voice from a model (safetensors repo, .gguf, or
                        URL)
    cast                Cast a voice onto a .gguf or .safetensors file
    delta               Make a reusable style (voice − base)
    graft               Graft one voice onto another (DELLA single graft)
    chorus              Blend voices: pulse + support + lead (DELLA chorus)
    add                 Add a voice from local voice.safetensors + voice.json
    list                List stored voices
    info                Show voice details
    remove              Remove a stored voice
    cleanup             Remove incomplete downloads
    auth                Save your HF token (optional)
    report              Save a report locally and optionally share to
                        community
    path                Put voice on your PATH
    doctor              Check your setup

options:
  -h, --help            show this help message and exit
  -v, --verbose         Verbose: tensor shapes, decisions, and paths
  --non-interactive     Fail instead of prompting (same as piped stdin; needs
                        --yes to overwrite/remove)
  --version             Show version and environment
  --completion {bash,zsh,fish}
                        Print shell completion script
```

## voice get

```text
usage: voice get [-h] [-q] [--name NAME] [--multi] [--out OUT] [--yes]
                 source [tensors ...]

positional arguments:
  source       HF model ID, .gguf/.safetensors path, or URL
  tensors      Tensor name(s) to fetch (default: auto-detect output head; 2+
               or --multi saves a voicepack)

options:
  -h, --help   show this help message and exit
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
  --name NAME  Voice name to save (registry voices only; not with --out)
  --multi      Fetch the named tensors (1+) as voicepack.safetensors +
               voicepack.json (not with --name)
  --out OUT    Write a standalone file instead of a registry voice (default
               pack name: voicepack.safetensors)
  --yes        Assume yes to prompts (overwrite without asking)
```

## voice cast

```text
usage: voice cast [-h] [--out OUT] [--yes] [--quant QUANT]
                  [--exclude EXCLUDES] [--speak] [-q]
                  target voice [tensors ...]

positional arguments:
  target              Path to the target .gguf or .safetensors
  voice               Voice name, or a .safetensors/.gguf path
  tensors             Only cast these tensors (default: every tensor in the
                      voice)

options:
  -h, --help          show this help message and exit
  --out OUT           Output file or folder (default:
                      ~/Voiced/<voice>-<model>/<voice>-<model>.<ext matching
                      target>; a folder invents the filename)
  --yes               Assume yes to prompts (overwrite without asking)
  --quant QUANT       Output quant override: keep (default, preserve quality)
                      | target | any quant
                      (q8_0,q4_0,q4_k,q6_k,iq4_nl,f16,f32,bf16,...;
                      safetensors targets: keep|target|f32|f16|bf16)
  --exclude EXCLUDES  Skip tensors on cast (repeatable: --exclude foo
                      --exclude bar, or --exclude foo,bar)
  --speak             Voice speaks through output.weight (invented if absent
                      when head/embed geometry survives; GGUF targets only)
  -q, --quiet         Quieter: progress and success notes off (warnings and
                      errors still print)
```

## voice delta

```text
usage: voice delta [-h] [--base BASE] [--yes] [-q] [voicename]

positional arguments:
  voicename    Voice name (default: pick from registry)

options:
  -h, --help   show this help message and exit
  --base BASE  Base HF repo (org/model) or local path to base safetensors
  --yes        Assume yes to prompts (overwrite without asking)
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice graft

```text
usage: voice graft [-h] [--density DENSITY] [--epsilon EPSILON]
                   [--lambda_ LAMBDA_] [--rescale {l1,inv_p}] [--seed SEED]
                   [--out OUT] [--yes] [-q]
                   [pulse] [donor]

positional arguments:
  pulse                 Pulse voice name (default: pick from registry)
  donor                 Donor voice name (default: pick from registry)

options:
  -h, --help            show this help message and exit
  --density DENSITY     Keep-fraction for magnitude pruning (default: 0.8)
  --epsilon EPSILON     Rank-ramp half-width (default: 0.1)
  --lambda_ LAMBDA_     Global rescale after combine (default: 1.0)
  --rescale {l1,inv_p}  Prune rescale: l1 (stable) or inv_p (paper-faithful)
  --seed SEED           Bernoulli seed for reproducible grafts (default: 42)
  --out OUT             Output voice name (default: chorus-<pulse>-<donor>)
  --yes                 Assume yes to prompts (overwrite without asking)
  -q, --quiet           Quieter: progress and success notes off (warnings and
                        errors still print)
```

## voice chorus

```text
usage: voice chorus [-h] [--config] [--density DENSITY]
                    [--lead-density LEAD_DENSITY] [--epsilon EPSILON]
                    [--lead-epsilon LEAD_EPSILON] [--lambda_ LAMBDA_]
                    [--rescale {l1,inv_p}] [--seed SEED] [--out OUT] [--yes]
                    [-q]
                    [pulse] [donors ...]

positional arguments:
  pulse                 Pulse voice name (default: pick interactively)
  donors                Support + lead voice names (0-2; 1 = duet at lead
                        density)

options:
  -h, --help            show this help message and exit
  --config              Stage knob screens per graft (Enter accepts each
                        default; screens prefill from flags)
  --density DENSITY     First-graft density (default: 0.8)
  --lead-density LEAD_DENSITY
                        Lead-graft density (default: 0.9)
  --epsilon EPSILON     Rank-ramp half-width (default: 0.1)
  --lead-epsilon LEAD_EPSILON
                        Lead-graft epsilon (default: 0.05; keeps 0.9±eps
                        valid)
  --lambda_ LAMBDA_     Global rescale after combine (default: 1.0)
  --rescale {l1,inv_p}  Prune rescale: l1 (stable) or inv_p (paper-faithful)
  --seed SEED           Bernoulli seed for reproducible choruses (default: 42)
  --out OUT             Final output voice name (default:
                        chorus-<pulse>-<lead>)
  --yes                 Assume yes to prompts (overwrite without asking)
  -q, --quiet           Quieter: progress and success notes off (warnings and
                        errors still print)
```

## voice add

```text
usage: voice add [-h] [--name NAME] [--yes] [-q] safetensors json

positional arguments:
  safetensors  Path to voice.safetensors (required)
  json         Path to voice.json (required)

options:
  -h, --help   show this help message and exit
  --name NAME  Voice name to save (default from voice.json)
  --yes        Auto-confirm overwrite
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice list

```text
usage: voice list [-h] [--base] [-q] [base]

positional arguments:
  base         Show cached base heads (same as --base)

options:
  -h, --help   show this help message and exit
  --base       Show cached base heads instead of voices
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice info

```text
usage: voice info [-h] [-q] voicename

positional arguments:
  voicename    Voice name

options:
  -h, --help   show this help message and exit
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice remove

```text
usage: voice remove [-h] [--yes] [-q] voice

positional arguments:
  voice        Voice name

options:
  -h, --help   show this help message and exit
  --yes        Assume yes to prompts (remove without asking)
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice cleanup

```text
usage: voice cleanup [-h] [--force] [-q]

options:
  -h, --help   show this help message and exit
  --force      Also clear in-progress downloads (locked)
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice auth

```text
usage: voice auth [-h] [--clear] [--show] [-q]

options:
  -h, --help   show this help message and exit
  --clear      Remove the stored token
  --show       Show the masked token
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice report

```text
usage: voice report [-h] [--message MESSAGE] [--voice VOICE] [--target TARGET]
                    [--reporter REPORTER] [--yes] [--no-push] [--sync] [-q]

options:
  -h, --help            show this help message and exit
  --message, -m MESSAGE
                        Freeform note (240ch, sanitized)
  --voice VOICE         Voice name context
  --target TARGET       Target file basename context
  --reporter REPORTER   Reporter id (optional, 64ch)
  --yes                 Non-interactive: skip preview and auto-share to
                        community
  --no-push             Local only, skip share prompt
  --sync                Sync pending outbox to community
  -q, --quiet           Quieter: progress and success notes off (warnings and
                        errors still print)
```

## voice path

```text
usage: voice path [-h] [-q]

options:
  -h, --help   show this help message and exit
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```

## voice doctor

```text
usage: voice doctor [-h] [-q]

options:
  -h, --help   show this help message and exit
  -q, --quiet  Quieter: progress and success notes off (warnings and errors
               still print)
```