CLI - User Guide¶

The CodeFetch CLI is a terminal tool for retrieving and running scripts from your CodeFetch library. Scripts are stored encrypted on the server and decrypted on your machine — your secret key never leaves your device.

Installation¶

Linux / macOS

curl -fsSL https://github.com/codefetch-io/codefetch-releases/releases/latest/download/install.sh | bash

Windows (PowerShell)

iwr https://github.com/codefetch-io/codefetch-releases/releases/latest/download/install.ps1 | iex

Homebrew (macOS / Linux)

brew tap hsops/codefetch https://github.com/codefetch-io/homebrew-tap.git
brew install codefetch

Chocolatey (Windows)

choco source add -n hsops-codefetch -s https://nuget.cloudsmith.io/hsops/codefetch/v2/
choco install codefetch

Verify the install:

codefetch version

First-time Setup¶

Run the setup wizard:

codefetch config

You will be prompted for two values:

Credentials are encrypted with a machine-specific key and stored locally — they are never sent anywhere beyond authenticating to your CodeFetch server.

To update your credentials at any time, run codefetch config again. To wipe and start fresh:

codefetch config --reset

Browsing Your Library¶

Open the interactive browser:

codefetch list

Running codefetch with no arguments does the same thing.

The right-hand panel shows the selected script's ID, filename, tags, language, size, and last updated date.

Navigation¶

Actions on the selected script¶

Searching by Tag¶

codefetch search docker
codefetch search docker,nginx,ssl

Opens the same browser pre-filtered to scripts matching those tags. Matching is substring-based — dep matches deploy.

Running a Script by ID¶

codefetch get BC91EBCD

Fetches the script, decrypts it, writes it to a temp file, and executes it. On Linux and macOS the script must have a valid shebang line (e.g. #!/usr/bin/env bash). On Windows, .ps1 files run via PowerShell and everything else runs via cmd.exe.

Save instead of run¶

codefetch get BC91EBCD --save

Saves the decrypted script to your temp directory as {ID}.{extension} (e.g. BC91EBCD.sh) and copies the path to your clipboard. Useful when you want to inspect before running, or for file types that need manual execution.

On Linux, copying to the clipboard requires xclip or xsel to be installed (e.g. sudo apt install xclip). Without one of these, the file still saves — only the clipboard copy is skipped.

Source into the current shell¶

# bash / zsh
eval $(codefetch get BC91EBCD --source)

# PowerShell
Invoke-Expression (codefetch get BC91EBCD --source)

Outputs the decrypted script content to stdout so you can source it directly into your current shell session — useful for scripts that set environment variables or define functions.

CI/CD — No Config File Needed¶

Pass credentials inline with any command using global flags:

codefetch get BC91EBCD --auth-uri https://app.codefetch.io/{tenantId} --auth-secret mysecret

Both flags must be provided together. These bypass the saved config entirely and are designed for pipelines where you can't persist a config file.

Shared Links¶

Anyone can run a shared script without a CodeFetch account. The share URL contains the decryption key — no login required.

codefetch link "https://app.codefetch.io/links/tenant/token?sig=abc123"

Supports the same --save and --source flags as codefetch get.

Creating and managing shared links is done from the TUI browser:

When you rotate a link, the old URL is immediately invalidated and a new one is generated.

Playbooks¶

A playbook is a JSON file that runs a sequence of scripts in order. This is useful for multi-step workflows like environment setup or deployment pipelines.

Export a playbook from a tag search¶

codefetch playbook export docker my-playbook.json

Searches for scripts tagged docker, sorts them by their #1, #2, #3 sequence tags, and writes the playbook file.

Building a playbook interactively¶

You can also assemble a playbook from inside the TUI browser instead of exporting from a tag search:

1. Press Ctrl+P in the library browser to enter playbook builder mode.
2. Press Space on any script to toggle it in or out of the selection — scripts are numbered in the order you pick them ([1], [2], ...), which becomes their run order.
3. Press Ctrl+E to open the export dialogue and save the selection to a playbook JSON file.
4. Press Ctrl+P again to exit playbook builder mode and return to normal browsing.

Run a playbook¶

codefetch playbook run my-playbook.json

Fetches and runs each script in order. If one script fails, the error is printed and the playbook continues with the next entry.

Playbook file format¶

[
  { "id": "BC91EBCD", "filename": "setup.sh",  "tags": ["docker", "#1"] },
  { "id": "A1B2C3D4", "filename": "deploy.sh", "tags": ["docker", "#2"] },
  { "id": "E5F6G7H8", "filename": "verify.sh", "tags": ["docker", "#3"] }
]

Scripts are ordered by #N tag. Scripts without a sequence tag run last.

Keep playbooks platform-specific — a playbook mixing .sh and .ps1 scripts will fail on the wrong OS.

Shorty URL Shortener¶

If you have a Shorty instance, you can create short vanity URLs alongside full share links (e.g. https://yourdomain.com/deploy instead of the full signed URL).

Configure Shorty¶

codefetch shorty

Prompts for your Shorty admin endpoint and API key. Credentials are encrypted and stored locally alongside your CodeFetch config.

Use Shorty from the TUI¶

With Shorty configured, two extra controls appear in the browser:

When you delete a shared link with Ctrl+D, the corresponding Shorty entry is also removed.

Shell Completion¶

Tab-completion for subcommands and flags.

bash

echo 'source <(codefetch completion bash)' >> ~/.bashrc && source ~/.bashrc

zsh

echo 'source <(codefetch completion zsh)' >> ~/.zshrc && source ~/.zshrc

fish

codefetch completion fish > ~/.config/fish/completions/codefetch.fish

PowerShell

codefetch completion powershell >> $PROFILE

Quick Reference¶