gpm - A swiss army knife written in and for Go

Copyright by Marcel Joachim Kloubert, created with Midjourney

Overview [↑]

gpm is a command-line tool designed to simplify developer workflows in particular for Go projects.

However, it's not only limited to Go but can also be utilized for other project types as well.

KEEP IN MIND: This project is in an beta state and under heavy development. It might happen that there will be breaking changes. Have a look at the CHANGELOG.md file.

Installation [↑]

You can install gpm from a pre-build binary or build it by your own:

MacOS / Linux / UNIX [↑]

You can simply execute the follow remote shell script:

wget -qO- "https://sh.kloubert.dev/gpm.sh" | sh

Later you can run the command again to update the tool as well.

Windows [↑]

You can simply execute the follow remote PowerShell script:

Invoke-WebRequest -Uri "https://sh.kloubert.dev/gpm.ps1" | Select-Object -ExpandProperty Content | Invoke-Expression

Later you should be able to run the command again to update the tool as well.

Build from source [↑]

# checkout current source
git clone https://github.com/mkloubert/go-package-manager.git -o gpm

# switch to new subfolder, build and run it
cd gpm
go build . && ./gpm --version

Updates [↑]

A self-update works with

gpm update --self

if you have a valid sh or PowerShell installed.

You are able to customize final directory with GPM_INSTALL_PATH, which is C:\Program Files\gpm on Windows and /usr/local/bin on POSIX-like systems by default e.g.

Usage [↑]

Commands [↑]

Add alias [↑]

With

gpm add alias yaml https://github.com/go-yaml/yaml

you define the alias yaml which refers to the Git repository in https://github.com/go-yaml/yaml. This information will be stored in aliases.yaml file inside your <GPM-ROOT> folder.

If you later run

gpm install yaml

go get -u https://github.com/go-yaml/yaml will be executed instead.

Add project [↑]

With

gpm add project react-project https://github.com/ofnullable/react-spa-template

you define the alias react-project which refers to the Git repository in https://github.com/ofnullable/react-spa-template. This information will be stored in projects.yaml file inside your <GPM-ROOT> folder.

If you later run

gpm new react-project

the repository will be cloned to react-spa-template subfolder, then its .git folder will be removed and the new folder will be re-initialized with git init.

AI chat [↑]

AI image description [↑]

AI prompt [↑]

Build and install executable [↑]

gpm make https://github.com/gohugoio/hugo

will clone the repository into a temp folder and run gpm build from it.

The final executable will be installed in <GPM-ROOT>/bin folder. So it could be useful to add it to the $PATH enviornment variable.

FYI: Instead of the URL as argument you can use a project alias added by add project command.

Build project [↑]

gpm build

will run go build . in the current directory or the build script in gpm.yaml, if defined.

Bump version [↑]

The simple execution of

gpm bump

will detect the latest version of the underlying repository from Git tags and then upgrade the minor part only, e.g. 1.2.4 => 1.3.0. Finally a new Git tag is created in the format v1.3.0.

You also can use at least one of the following flags to increase parts of the current version number as well:

--breaking: 1.2.4 => 2.0.0 by default
--feature: 1.2.4 => 1.3.0 by default
--fix: 1.2.4 => 1.2.5

Checkout branch [↑]

The execution of

gpm checkout my-branch

will checkout or create the branch my-branch in the current Git repository.

If the branch does not exist, you can use --suggest to use AI which generates a branch name from a description using format <type>/<description>.

An execution of

gpm checkout "i will fix the save button on start page" --suggest

for example could suggest a value like feature/fix-save-button-on-start-page when using ChatGPT 3.5

Have a look at the Setup AI which describes how to setup OpenAI or Ollama API.

Branch aliases [↑]

For example, if you define the environment variable GPM_BRANCH_DEV with development as value, you can run

gpm checkout :dev

from the command line to switch to development branch.

The :dev is the part after the GPM_BRANCH_ prefix in the environment variable name.

This means you are also able to define a variable, lets say GPM_BRANCH_FOO, with the value bar, which will allow you to easily switch to bar branch if you execute

gpm checkout :foo

Keep in mind: If you have no value for an alias defined, gpm will take its name as fallback!

Checkup project [↑]

The following demo shows how gpm doctor works:

Cleanup project [↑]

gpm tidy

is a short form of go mod tidy.

Clone project [↑]

This command allows you to clone a known project using a shorter alias.

For example, if you’ve added a project named hugo with

gpm add project https://github.com/gohugoio/hugo

you can later clone it with a simple

gpm clone hugo

which is a shorthand for git clone https://github.com/gohugoio/hugo, what means that you are able to add any clone argument with your installed Git command version:

# clone to subfolder my-projects/the-great-hugo-project
# and get only the last / head commit
gpm clone hugo my-projects/the-great-hugo-project --depth 1

Compare code changes [↑]

Compression [↑]

# compress LICENSE with gzip
gpm compress ./LICENSE > ./LICENSE.gz

# decompress LICENSE.gz with gzip
gpm uncompress ./LICENSE.gz > ./LICENSE_unzipped

Cron jobs [↑]

# run `date` every second
gpm cron "@every 1s" date

# run `date` every 2 minutes at :30
gpm cron "30 */2 * * * *" date

For more information about the cron syntax, you can visit documentation page of the underlying module.

Docker shorthands [↑]

Shorthand	Final command
`gpm down`	`docker compose down`
`gpm up`	`docker compose up --build`

Encoding [↑]

# encode HTTP resource with Base64
gpm cat "https://avatars.githubusercontent.com/u/4951215?v=4" | gpm base64 --data-uri > gitfather_avatar.base64.txt

Execute shell command [↑]

Generate documentation [↑]

Running the following command

gpm generate documentation

will generate the full documentation for this tool as Markdown in the current directory.

To output the documentation into a specific folder, use:

gpm generate documentation my-doc-folder

Generate PowerPoint [↑]

The following command will execute the default command template pandoc -t pptx -o "{{.OutputFile}}" "{{.InputFile}}" by creating out.pptx file from Markdown code, saved into {{.InputFile}}, which will be generated by AI:

gpm generate powerpoint out.pptx my-text-file1.txt *.go README.md --language=german

In this case Pandoc must be installed on your system.

You can change the template by using --template flag or GPM_GENERATE_PPTX_FROM_MD_COMMAND environment variable, if you want to use another command.

Generate project [↑]

To generate a new Go project tailored to your requirements, execute the following command:

gpm generate project --output=./my-new-project example.com/foo/example "i need a starter backend with gin, i also need api key check and logging"

This command prompts the default AI provider to create a step-by-step plan for setting up a Go project based on your input i need a starter backend with gin, i also need api key check and logging.

The process begins by initializing a new project with the URL example.com/foo/example in the my-new-project folder. Each step in the setup is executed interactively, with user input guiding the workflow.

Once all steps are completed, the AI generates a summary in the standard output. This summary explains the actions performed and their purpose, ensuring the project aligns with the specified requirements.

The following video does demonstrate this (keep in mind: replace replace go run . <...> with gpm <...> later):

Import aliases [↑]

gpm import aliases https://raw.githubusercontent.com/mkloubert/go-package-manager/main/aliases.yaml

loads aliases from https://raw.githubusercontent.com/mkloubert/go-package-manager/main/aliases.yaml and merge them with entries in aliases.yaml file in <GPM-ROOT> folder.

You can also use a local file path and/or pipe from STDIN as well.

Import projects [↑]

gpm import projects https://raw.githubusercontent.com/mkloubert/go-package-manager/main/projects.yaml

loads projects from https://raw.githubusercontent.com/mkloubert/go-package-manager/main/projects.yaml and merge them with entries in projects.yaml file in <GPM-ROOT> folder.

You can also use a local file path and/or pipe from STDIN as well.

Install dependencies [↑]

gpm install <alias> is designed to install a module via an alias defined with Add alias command.

For example if you define an alias called yaml with

gpm add alias yaml https://github.com/go-yaml/yaml

you can run

gpm install yaml

later which will simply call go get -u https://github.com/go-yaml/yaml instead.

List aliases [↑]

Simply run

gpm list aliases

will output a list like this:

cobra
        https://github.com/spf13/cobra
mongo
        go.mongodb.org/mongo-driver/mongo
yaml
        https://github.com/go-yaml/yaml

List executables [↑]

Executables / binaries created with make command can be listed with

gpm list binaries

List projects [↑]

Simply run

gpm list projects

will output a list like this:

mkloubert
        git@github.com:mkloubert/mkloubert.git

Monitor process [↑]

New project [↑]

gpm new <project> is designed to setup a project via an alias defined with Add project command.

For example if you define an alias called mkloubert with

gpm add project mkloubert git@github.com:mkloubert/mkloubert.git

you can run

gpm new mkloubert

later which will simply call git clone git@github.com:mkloubert/mkloubert.git instead that clones the Git repository to mkloubert subfolder, removes its .git folder and re-initializes it with git init.

Open alias [↑]

Aliases created by Add alias command can be opened by default handler of the operating system.

Lets say you created an alias called cobra with the URL https://github.com/spf13/cobra, the execution of

gpm open alias cobra

will open this URL usually in the browser.

Open project [↑]

Project entries created by Add project command can be opened by default handler of the operating system.

Lets say you created a project alias called gpm with the URL https://github.com/mkloubert/go-package-manager, the execution of

gpm open project cobra

will open this URL usually in the browser.

Pack project [↑]

Passwords and unique IDs [↑]

# directly generate password and copy to clipboard
gpm password --no-output --copy

# generate and output UUID
gpm uuid

Publish new version [↑]

Running

gpm publish

will bump the feature part of the project's current version represented by Git tags.

After this, the code will be pushed to all remotes, including tags as well.

Pull from Git remotes [↑]

The execution of

gpm pull

will pull from all remotes which are stored inside the current Git repository.

Push to Git remotes [↑]

The execution of

gpm push

will push to all remotes which are stored inside the current Git repository.

Remove alias [↑]

With

gpm remove alias yaml

you will remove the yaml alias from aliases.yaml file, which is stored in <GPM-ROOT> folder.

Remove project [↑]

With

gpm remove project yaml

you will remove the yaml alias from projects.yaml file, which is stored in <GPM-ROOT> folder.

Remove executable [↑]

If you installed a binary with make command like

gpm make https://github.com/gopasspw/gopass

you can simply remove it with gpm remove binary gopass if the binary is stored as gopass in <GPM-ROOT>/bin folder.

Run script [↑]

In the gpm.yaml file you can define script which are executed in shell/terminal context:

scripts:
  foo: "echo bar"

With

gpm run foo

you will run echo bar.

Run tests [↑]

gpm test

will execute go test . instead or the test script defined in current gpm.yaml file, if defined.

Show dependency graph [↑]

Running

gpm show dependencies

will create and open a temporary HTML file which will display a dependency graph of all installed modules:

Sleep [↑]

gpm sleep 10s

The command uses build-in duration format.

Start project [↑]

gpm start

will execute go run . instead or the start script defined in current gpm.yaml file, if defined.

Synchronize with Git remotes [↑]

With execution of

gpm sync

you will pull from and then push to all remotes as defined in the current Git repository.

Uninstall dependencies [↑]

gpm uninstall <alias> is designed to un-install a module via an alias defined with Add alias command.

For example if you define an alias called yaml with

gpm add alias yaml https://github.com/go-yaml/yaml

you can run

gpm uninstall yaml

later which will simply call go get -u https://github.com/go-yaml/yaml@none instead.

Update dependencies [↑]

gpm update

is a short version of go get -u ./... && go mod tidy and will update all dependencies.

On the other hand, you are able to run something like

gpm update github.com/alecthomas/chroma yaml

to update specific ones. Each argument can be a module URL or alias.

Setup AI [↑]

If you would like to use AI feature, like suggestion of branch names, you can setup one of the following APIs:

OpenAI / ChatGPT [↑]

Create (or use) an API from https://platform.openai.com/api-keys and write it to OPENAI_API_KEY environment variable.

By default gpt-4o-mini model is used. You can change this, by setting up GPM_AI_CHAT_MODEL environment variable with a value from here like this:

GPM_AI_CHAT_MODEL=gpt-4-turbo

Ollama [↑]

If you want to use Ollama instead, you have to setup the following environment variables:

GPM_AI_API=ollama
GPM_AI_CHAT_MODEL=<name of the model>

Replace <name of the model> with one of these models.

Two good models are llama3 by Meta or phi3 by Microsoft.

gpm.yaml [↑]

The idea of an gpm.yaml file is very similar to package.json file for Node / NPM environments.

An example can be found here.

If you want to initialize an empty one, you only need to execute

gpm init

in your terminal.

Files [↑]

The files section contains a list of regular expressions that specify which files are included by the pack command:

# ...

files:
  - my-app
  - LICENSE
  - README.md
  - ^commands/p
# ...

If the list is empty or not defined, the following default values are applied:

the potential name of the executable file built with the build command
^CHANGELOG.md$
^CONTRIBUTING.md$
^CONTRIBUTION.md$
^LICENSE$
^README.md$

You can also define environment-specific file lists to customize behavior for different environments:

# ...

"files:dev":
  - my-dev-app
  - README.dev.md
  - ^commands/p
# ...

When files:dev is defined, it takes precedence over the files list, allowing you to tailor the included files for specific environments.

Scripts [↑]

To configure your scripts, add or update the scripts section with key/value pairs as shown below:

scripts:
  test1: "echo Test1"
  test2: "echo Test2"

Once defined, you can run the commands directly from your project folder using gpm run test1 or gpm run test2.

You can also create environment-specific scripts to customize behavior for different environments:

scripts:
  test1: "echo Test1 runs in the default environment"
  dev:test1: "echo Test1 runs in the 'dev' environment"

When executing gpm run test1 --environment=dev, the command will prioritize dev:test1 over test1. This allows you to tailor scripts for specific environments easily.

Predefined [↑]

Name	Description
`build`	Custom logic for build command.
`bump`	Custom logic for bump command.
`postbuild`	Is executed after successful execution of build command.
`postinstall`	Is executed after successful execution of install command.
`postbump`	Is executed after successful execution of bump command.
`postpublish`	Is executed after successful execution of publish command.
`posttest`	Is executed after successful execution of test command.
`posttidy`	Is executed after successful execution of tidy command.
`prebuild`	Is executed before build command is executed.
`prebump`	Is executed before bump command is executed.
`preinstall`	Is executed before install command is executed.
`prepublish`	Is executed before publish command is executed.
`prestart`	Is executed before start command is executed.
`pretest`	Is executed before test command is executed.
`pretidy`	Is executed before tidy command is executed.
`publish`	Custom logic for publish command.
`start`	Is executed by start command. If not defined `go run .` is executed.
`test`	Is executed by test command. If not defined `go test .` is executed.
`tidy`	Is executed by tidy command. If not defined `go mod tidy` is executed.

Environment variables [↑]

Environment variables can be loaded from external files, which are handled in this order:

<GPM-ROOT>/.env (if exist)
<PROJECT-DIR>/.env (if exist)
<PROJECT-DIR>/.env<SUFFIX> (if exist)
<PROJECT-DIR>/.env.local (if exist)
<PROJECT-DIR>/.env<SUFFIX>.local (if exist)
from --env-file flags (must exist!)

<SUFFIX> is the lower case value from --environment and can be empty.

Supported variables [↑]

Name	`settings.yaml`	Description	Example
`GPM_AI_API`	`ai.api`	ID of the AI API to use. Possible values are `ollama` or `openai`.	`openai`
`GPM_AI_CHAT_MODEL`	`ai.chat.model`	ID of the AI chat model to use. Possible values are models by OpenAI or Ollama.	`gpt-4o`
`GPM_AI_CHAT_TEMPERATURE`	`ai.chat.temperature`	Temperature value for an AI chat (operation)	`0`
`GPM_AI_PROMPT`	`ai.prompt`	Custom prompt for operations which are using chat completion operations, like checkout command.
`GPM_AI_SYSTEM_PROMPT`	`ai.system.prompt`	Custom (initial) system prompt for AI chat operations.	`You are a helpful AI assistant. You always answer in a very sarcastic way.`
`GPM_ALIASES_FILE`	`aliases.file`	Custom path to aliases.yaml file. Relative paths will be mapped to `<GPM-ROOT>`. Default is `<GPM-ROOT>/aliases.yaml`.	`/my/custom/aliases/file.yaml`
`GPM_BIN_PATH`		Custom folder for binaries installed by make command. Default is `<GPM-ROOT>/bin`.	`/my/custom/bin/path`
`GPM_DEFAULT_ALIAS_SOURCE`		Custom source for source of alias imports. Multiple sources can be separated by lines.	`https://example.com/gpm-aliases.yaml`
`GPM_DEFAULT_PROJECT_SOURCE`		Custom source for source of project imports. Multiple sources can be separated by lines.	`https://example.com/gpm-projects.yaml`
`GPM_DOWN_COMMAND`	`down.command`	Custom command for docker compose down shorthand.	`docker-compose down`
`GPM_ENV`		ID of the current environment. This is especially used for the .env files.	`prod`
`GPM_GENERATE_PPTX_FROM_MD_COMMAND`	`generate.pptx.from.md.command`	Template for a command that generates a PowerPoint presentation from a Markdown file.	`pandoc -t pptx -o "{{.OutputFile}}" "{{.InputFile}}`
`GPM_INSTALL_PATH`		Custom installation path of global `gpm` binary.	`/usr/bin`
`GPM_PROJECTS_FILE`	`projects.file`	Custom path to projects.yaml file. Relative paths will be mapped to `<GPM-ROOT>`. Default is `<GPM-ROOT>/projects.yaml`.	`/my/custom/projects/file.yaml`
`GPM_ROOT_BASE_PATH`		Custom root base folder for this application. Relative paths will be mapped to `$HOME`. Default is `$HOME/.gpm`.	`.my-gpm-folder-inside-home`
`GPM_SETTINGS_FILE`		Custom settings file.	`../path/to/settings/file.yaml`
`GPM_TERMINAL_FORMATTER`	`terminal.formatter`	Default formatter for syntax highlighting in terminal. See chroma project for more information.	`terminal16m`
`GPM_TERMINAL_STYLE`	`terminal.style`	Default style for syntax highlighting in terminal. See chroma project for more information.	`monokai`
`GPM_UP_COMMAND`	`up.command`	Custom command for docker compose up shorthand.	`docker-compose up`
`GPM_UPDATE_SCRIPT`		Custom URL to self-update script	`sh.kloubert.dev/gpm.sh`
`OPENAI_API_KEY`	`openai.api.key`	Key which is used for the API by OpenAI.	`sk-...`

Contribution [↑]

If you have ideas and/or want to participate you are welcome!

Open an issue or create a pull request.

Support [↑]

If you like the project you can donate via PayPal.

License [↑]

The project is licensed under the MIT.

Credits [↑]

gpm makes use of these following great projects:

asciinema + agg by asciinema team
Babel.js by Babel team
chroma by Alec Thomas
cobra by Steve Francia
cobra by Steve Francia
cron by Rob Figueiredo
gitignore by Shaba Abhiram
Glamour by Charm
go-prompt by c-bata
go-version by HashiCorp
go-yaml by Masaaki Goshima
godotenv by John Barton
gopsutil by shirou
Mermaid by Knut Sveidqvist and Sidharth Vinod
progressbar by Zack
React
spinner by Brian Downs
termui by Zack Guo
tview by rivo

Name		Name	Last commit message	Last commit date
Latest commit History 215 Commits
.github		.github
.vscode		.vscode
app		app
commands		commands
constants		constants
img		img
resources		resources
sh.kloubert.dev		sh.kloubert.dev
tests		tests
types		types
utils		utils
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
aliases.yaml		aliases.yaml
go.mod		go.mod
go.sum		go.sum
gpm.yaml		gpm.yaml
main.go		main.go
projects.yaml		projects.yaml

Uh oh!

Uh oh!

License

Uh oh!

mkloubert/go-package-manager

Folders and files

Latest commit

History

Repository files navigation

gpm - A swiss army knife written in and for Go

Table of contents

Overview [↑]

Installation [↑]

MacOS / Linux / UNIX [↑]

Windows [↑]

Build from source [↑]

Updates [↑]

Usage [↑]

Commands [↑]

Add alias [↑]

Add project [↑]

AI chat [↑]

AI image description [↑]

AI prompt [↑]

Build and install executable [↑]

Build project [↑]

Bump version [↑]

Checkout branch [↑]

Branch aliases [↑]

Checkup project [↑]

Cleanup project [↑]

Clone project [↑]

Compare code changes [↑]

Compression [↑]

Cron jobs [↑]

Docker shorthands [↑]

Encoding [↑]

Execute shell command [↑]

Generate documentation [↑]

Generate PowerPoint [↑]

Generate project [↑]

Import aliases [↑]

Import projects [↑]

Install dependencies [↑]

List aliases [↑]

List executables [↑]

List projects [↑]

Monitor process [↑]

New project [↑]

Open alias [↑]

Open project [↑]

Pack project [↑]

Passwords and unique IDs [↑]

Publish new version [↑]

Pull from Git remotes [↑]

Push to Git remotes [↑]

Remove alias [↑]

Remove project [↑]

Remove executable [↑]

Run script [↑]

Run tests [↑]

Show dependency graph [↑]

Sleep [↑]

Start project [↑]

Synchronize with Git remotes [↑]

Uninstall dependencies [↑]

Update dependencies [↑]

Setup AI [↑]

OpenAI / ChatGPT [↑]

Ollama [↑]

gpm.yaml [↑]

Files [↑]

Scripts [↑]

Predefined [↑]

Environment variables [↑]

Supported variables [↑]

Contribution [↑]

Support [↑]

License [↑]

Credits [↑]

Packages