> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudstic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cloudstic completion

> Generate shell completion scripts for bash, zsh, and fish

The `completion` command generates shell completion scripts that provide intelligent tab completion for Cloudstic commands, subcommands, flags, and values.

## Usage

```bash theme={null}
cloudstic completion <shell>
```

### Supported Shells

* **bash**: Bourne Again Shell
* **zsh**: Z Shell
* **fish**: Friendly Interactive Shell

## Installation

<Steps>
  <Step title="Generate the completion script">
    Run the completion command for your shell. The script is printed to stdout.

    ```bash theme={null}
    # Bash
    cloudstic completion bash

    # Zsh
    cloudstic completion zsh

    # Fish
    cloudstic completion fish
    ```
  </Step>

  <Step title="Load the completion script">
    Source the completion script in your current shell session or add it to your shell configuration file.

    ### Bash

    **For current session only:**

    ```bash theme={null}
    source <(cloudstic completion bash)
    ```

    **Permanent installation:**

    ```bash theme={null}
    # Add to ~/.bashrc or ~/.bash_profile
    echo 'source <(cloudstic completion bash)' >> ~/.bashrc
    ```

    **Alternative: Install to system completion directory**

    ```bash theme={null}
    cloudstic completion bash > /etc/bash_completion.d/cloudstic
    ```

    ### Zsh

    **For current session only:**

    ```bash theme={null}
    source <(cloudstic completion zsh)
    ```

    **Permanent installation:**

    ```bash theme={null}
    # Add to ~/.zshrc
    echo 'source <(cloudstic completion zsh)' >> ~/.zshrc
    ```

    **Alternative: Install to completion directory**

    ```bash theme={null}
    cloudstic completion zsh > "${fpath[1]}/_cloudstic"
    ```

    ### Fish

    **For current session only:**

    ```bash theme={null}
    cloudstic completion fish | source
    ```

    **Permanent installation:**

    ```bash theme={null}
    # Fish automatically loads completions from ~/.config/fish/completions/
    cloudstic completion fish > ~/.config/fish/completions/cloudstic.fish
    ```
  </Step>

  <Step title="Reload your shell or start a new session">
    For bash and zsh:

    ```bash theme={null}
    exec $SHELL
    ```

    For fish:

    ```bash theme={null}
    exec fish
    ```

    Or simply open a new terminal window.
  </Step>

  <Step title="Test the completion">
    Try typing `cloudstic ` and press Tab to see available commands:

    ```bash theme={null}
    cloudstic <TAB>
    # Shows: init backup auth store source setup tui profile restore list ls
    # prune forget diff break-lock key check cat completion version help
    ```
  </Step>
</Steps>

## Features

The completion scripts provide intelligent suggestions for:

### Commands and Subcommands

```bash theme={null}
cloudstic <TAB>
# Shows all available commands

cloudstic key <TAB>
# Shows: list add-recovery passwd
```

### Flags and Options

```bash theme={null}
cloudstic backup -<TAB>
# Shows: -source -tag -dry-run
# Plus all global flags

cloudstic init -<TAB>
# Shows: -add-recovery-key -no-encryption
# Plus all global flags
```

### Flag Values

```bash theme={null}
cloudstic backup -source <TAB>
# Shows: local sftp gdrive gdrive-changes onedrive onedrive-changes

cloudstic -store <TAB>
# Shows: local b2 s3 sftp
```

### File Path Completion

```bash theme={null}
cloudstic restore -output <TAB>
# Shows file completions
```

### Context-Aware Completions

The completion scripts understand the current command context:

```bash theme={null}
cloudstic backup -source local:<TAB>
# Shows directory completions for the local source path

cloudstic key passwd -<TAB>
# Shows: -new-password (plus global flags)
```

### Dynamic Completion for Profiles and Auth Entries

Unlike static flag values, `-profile` and `-auth-ref` are completed **dynamically**: the completion script shells out to `cloudstic __complete` under the hood, which reads your actual `profiles.yaml` and returns the live list of profile and auth-entry names.

```bash theme={null}
cloudstic backup -profile <TAB>
# Shows every profile name currently defined in profiles.yaml

cloudstic backup -auth-ref <TAB>
# Shows every auth entry name currently defined in profiles.yaml
```

This means completions always reflect the profiles and auth entries you've actually created, no regeneration required after editing `profiles.yaml`. The lookup honors `-profiles-file` / `CLOUDSTIC_PROFILES_FILE` if you point at a non-default profiles file, and silently returns no suggestions if the file doesn't exist yet or can't be parsed.

<Note>
  The `-profile` and `-auth-ref` flags are the only two with dynamic, file-backed completion. All other flag values (source types, store types, shell names, and so on) are completed from a static, built-in list.
</Note>

## Completion Examples

### Completing Store Types

```bash theme={null}
$ cloudstic backup -store <TAB>
local  b2  s3  sftp
```

### Completing Source Types

```bash theme={null}
$ cloudstic backup -source <TAB>
local  sftp  gdrive  gdrive-changes  onedrive  onedrive-changes
```

### Completing Subcommands

```bash theme={null}
$ cloudstic <TAB>
init        backup      auth        store       source      setup
tui         profile     restore     list        ls          prune
forget      diff        break-lock  key         check       cat
completion  version     help
```

### Completing Shell Types

```bash theme={null}
$ cloudstic completion <TAB>
bash  zsh  fish
```

## Troubleshooting

### Bash: Completions not working

1. Ensure `bash-completion` package is installed:
   ```bash theme={null}
   # Ubuntu/Debian
   sudo apt-get install bash-completion

   # macOS
   brew install bash-completion@2
   ```

2. Verify bash-completion is loaded in your `.bashrc`:
   ```bash theme={null}
   # Add if missing
   if [ -f /etc/bash_completion ]; then
     . /etc/bash_completion
   fi
   ```

### Zsh: Command not found: compdef

1. Enable `compinit` in your `.zshrc` before sourcing the completion:
   ```bash theme={null}
   autoload -Uz compinit
   compinit
   source <(cloudstic completion zsh)
   ```

### Fish: Completions not appearing

1. Check that the completion file was created:
   ```bash theme={null}
   ls ~/.config/fish/completions/cloudstic.fish
   ```

2. Reload completions:
   ```bash theme={null}
   fish_update_completions
   ```

### General: Old completions cached

If you update Cloudstic and completions don't reflect new commands:

```bash theme={null}
# Bash: Clear completion cache
hash -r

# Zsh: Clear completion cache
rm ~/.zcompdump*
compinit

# Fish: Reload completions
fish_update_completions
```

## Available Completions

The completion scripts provide suggestions for:

### Global Flags (available in all commands)

* `-store` → URI completion (shows format hints: `local:`, `s3:`, `b2:`, `sftp://`)
* `-s3-endpoint` → free text
* `-s3-region` → free text
* `-s3-access-key` → free text
* `-s3-secret-key` → free text
* `-store-sftp-password` → free text
* `-store-sftp-key` → file path completion
* `-store-sftp-known-hosts` → file path completion
* `-store-sftp-insecure` → boolean flag
* `-source-sftp-password` → free text
* `-source-sftp-key` → file path completion
* `-source-sftp-known-hosts` → file path completion
* `-source-sftp-insecure` → boolean flag
* `-encryption-key` → free text
* `-password` → free text
* `-recovery-key` → free text
* `-kms-key-arn` → free text
* `-disable-packfile` → boolean flag
* `-verbose` → boolean flag
* `-quiet` → boolean flag
* `-debug` → boolean flag

### Command-Specific Flags

**`init`**

* `-add-recovery-key`
* `-no-encryption`

**`backup`**

* `-source` → `local`, `sftp`, `gdrive`, `gdrive-changes`, `onedrive`, `onedrive-changes`
* `-tag` → free text (repeatable)
* `-ignore-empty-snapshot`
* `-dry-run`

**`restore`**

* `-output` → file or directory path completion (default: `./restore.zip`)
* `-format` → `zip` or `dir`
* `-path` → free text
* `-dry-run`

**`prune`**

* `-dry-run`

**`forget`**

* `-prune`
* `-dry-run`
* `-keep-last` → number
* `-keep-hourly` → number
* `-keep-daily` → number
* `-keep-weekly` → number
* `-keep-monthly` → number
* `-keep-yearly` → number
* `-tag` → free text (repeatable)
* `-source` → free text
* `-account` → free text
* `-path` → free text
* `-group-by` → free text (default: `source,account,path`)

**`cat`**

* `-json`

**`key passwd`**

* `-new-password` → free text

**`check`**

* `-read-data`

## Notes

* **Performance**: Completions are generated dynamically based on the current command context
* **File completions**: File and directory paths use native shell completion capabilities
* **No external dependencies**: Completion scripts are self-contained and don't require network access
* **Automatic updates**: Regenerate completions after upgrading Cloudstic to get the latest commands and flags

## Related Commands

* : Display usage information
* : Print version information