💻 Command line interface

Sheldon has three different types of commands.

  • init initializes a new config file.
  • lock and source deal with plugin downloading, installation, and generation of shell source code.
  • add, edit, and remove automate editing of the config file.

init

This command initializes a new config file. If a config file exists then this command does nothing.

For example

sheldon init

Or you can specify the shell.

sheldon init --shell bash

or

sheldon init --shell zsh

lock

The lock command installs the plugins sources and generates the lock file (~/.sheldon/plugins.lock). Rerunning this command without any extra options will not reinstall plugin sources, just verify that they are correctly installed. It will always regenerate the lock file.

sheldon lock

To update all plugin sources you can use the --update flag.

sheldon lock --update

To force a reinstall of all plugin sources you can use the --reinstall flag.

sheldon lock --reinstall

source

This command generates the shell script. This command will first check if there is an up to date lock file, if not, then it will first do the equivalent of the lock command above. This command is usually used with the built-in shell eval command.

eval "$(sheldon source)"

But you can also run it directly to inspect the output. The output of this command is highly configurable. You can define your own custom templates to apply to your plugins.

add

This command adds a new plugin to the config file. It does nothing else but edit the config file. In the following command we add a GitHub repository as a source.

sheldon add my-repo --git https://github.com/owner/repo.git

An example usage of this command for each source type is shown in the Configuration section.

edit

This command will open the config file in the default editor and only overwrite the contents if the updated config file is valid. To override the editor that is used you should set the EDITOR environment variable.

For example using vim

EDITOR=vim sheldon edit

Or with Visual Studio Code

EDITOR="code --wait" sheldon edit

remove

This command removes a plugin from the config file. It does nothing else but edit the config file. In the following command we remove the plugin with name my-repo.

sheldon remove my-repo

Flags

Sheldon accepts the following global command line flags.

FlagDescription
-q, --quietSuppress any informational output
-v, --verboseUse verbose output
-h, --helpShow the help message and exit
-V, --versionShow the version and exit

Options

Sheldon accepts the following global command line options.

OptionEnvironment variableDescription
--color <when>Output coloring: always, auto, never. (default: auto)
--home <path>HOMESet the home directory. (default: auto)
--config-dir <path>SHELDON_CONFIG_DIRSet the config directory. (default: <home>/.sheldon)
--data-dir <path>SHELDON_DATA_DIRSet the data directory. (default: <home>/.sheldon)
--config-file <path>SHELDON_CONFIG_FILESet the config file. (default: <config_dir>/plugins.toml)
--lock-file <path>SHELDON_LOCK_FILESet the lock file. (default: <data_dir>/plugins.lock)
--clone-dir <path>SHELDON_CLONE_DIRSet the clone directory. (default: <data_dir>/repos)
--download-dir <path>SHELDON_DOWNLOAD_DIRSet the download directory. (default: <data_dir>/downloads)

The priority order for setting these values is the following

  1. Command line option.
  2. Environment variable.
  3. Default value.