Packages

Packages let you install themes, plugins, and completions from GitHub. You can also create your own packages to share with others.

What is a Package?

A package is a Git repository containing any combination of:

• Themes - Prompt appearance configurations
• Plugins - Custom prompt variables
• Completions - Tab completion definitions

When you install a package, nosh clones it to ~/.config/nosh/packages/ and makes everything inside available to use.

Installing Packages

From GitHub

The easiest way is using GitHub shorthand:

/install user/repo

For example:

/install starship/nosh-themes

This clones https://github.com/starship/nosh-themes to ~/.config/nosh/packages/nosh-themes/.

From any Git URL

You can also use a full URL:

/install https://github.com/user/repo
/install https://gitlab.com/user/repo

Using Package Content

Themes

After installing, set the theme in ~/.config/nosh/config.toml:

[prompt]
theme = "nosh-themes/gruvbox"

The format is package-name/theme-name.

Plugins

Reference package plugins in your theme:

format = "[{cool-plugins/k8s:context}](cyan)"

[plugins]
"cool-plugins/k8s" = { enabled = true }

Completions

Completions work automatically. Once a package is installed, tab completion for any commands it defines is available immediately.

Updating Packages

The /sync command updates everything:

/sync

This does two things:

1. Updates builtins - Syncs built-in themes, plugins, and completions with the version embedded in nosh
2. Updates git packages - Runs git pull on each installed package

Example output:

Checking for updates...

Builtins:
  Up to date: Default theme
  Updated: Context plugin
  Up to date: Git completions

Packages:
  Updated: nosh-themes
  Up to date: cool-plugins

2 item(s) updated.

Managing Packages

List and remove packages:

/packages

This shows all installed packages with their contents and gives you the option to remove them.

Creating Your Own Package

Want to share your themes or plugins? Create a package!

Step 1: Create the repository structure

my-nosh-package/
├── themes/           # Optional
│   ├── dark.toml
│   └── light.toml
├── plugins/          # Optional
│   └── myinfo.toml
└── completions/      # Optional
    └── mycli.toml

You need at least one of these directories with at least one file.

Step 2: Create your files

Example theme (themes/dark.toml):

[prompt]
format = """
[{dir}](#1e1e2e bold) \
[{builtins/context:git_branch}](#cba6f7){builtins/context:git_status} \
[{builtins/exec_time:took}](#6c7086)
[{prompt:char}](#89b4fa) """
char = "❯"
char_error = "❯"

[plugins]
"builtins/context" = { enabled = true }
"builtins/exec_time" = { enabled = true, min_ms = 500 }

[colors]
error = "#f38ba8"

Example plugin (plugins/myinfo.toml):

[plugin]
name = "myinfo"
description = "Custom system information"

[provides]
cpu = { command = "top -l 1 | grep 'CPU usage' | awk '{print $3}'" }
memory = { command = "memory_pressure | grep 'System-wide' | awk '{print $4}'" }

Example completion (completions/mycli.toml):

[completions.mycli]
description = "My CLI tool"

[completions.mycli.subcommands]
start = "Start the service"
stop = "Stop the service"
status = "Show status"

[completions.mycli.options]
"-v" = "Verbose output"
"--config" = { description = "Config file", takes_value = true, value_completer = "files" }

Step 3: Push to GitHub

git init
git add .
git commit -m "Initial commit"
gh repo create my-nosh-package --public
git push -u origin main

Step 4: Share it

Others can now install your package:

/install yourusername/my-nosh-package

How Packages are Stored

~/.config/nosh/
└── packages/
    ├── builtins/           # Built-in (not a git repo)
    │   ├── themes/
    │   ├── plugins/
    │   └── completions/
    ├── nosh-themes/        # Git package
    │   ├── .git/
    │   └── themes/
    └── cool-plugins/       # Git package
        ├── .git/
        └── plugins/

The packages.toml file tracks installed packages:

[packages.nosh-themes]
name = "nosh-themes"
source = "https://github.com/user/nosh-themes.git"
installed_at = "1707123456"
last_updated = "1707200000"

Naming Convention Summary

Source	Theme	Plugin	Completion
Built-in	builtins/default	{builtins/context:var}	Auto-loaded
Local	mytheme	{myplugin:var}	Auto-loaded
Package	pkg/theme	{pkg/plugin:var}	Auto-loaded

Troubleshooting

"Git is not installed"

Install git:

• macOS: xcode-select --install or brew install git
• Ubuntu/Debian: sudo apt install git
• Fedora: sudo dnf install git

"Could not clone repository"

• Check the URL is correct
• Make sure you have internet access
• For private repos, configure git credentials first

"Package already installed"

Use /sync to update existing packages, or /packages to remove and reinstall.

"Theme not found"

Make sure the package is installed:

1. Run /packages to see what's installed
2. If missing, run /install user/repo
3. Check the theme name matches: package-name/theme-name