cmd

package
v6.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 13, 2026 License: MIT Imports: 40 Imported by: 0

README

Command-line utilities

cmd/gutils builds the gutils executable. Install it with:

go install github.com/Laisky/go-utils/v6/cmd/gutils@latest

This guide describes the current v6 branch; a published version may lag it. See the root README for branch builds and more commands. Run gutils --help or gutils <command> --help to inspect available options.

Embedding commands

Append exported Cobra commands to your application's root command:

package main

import (
	gcmd "github.com/Laisky/go-utils/v6/cmd"
	"github.com/spf13/cobra"
)

// main builds a CLI containing the library's encryption and decryption commands.
func main() {
	root := &cobra.Command{Use: "my-tool"}
	root.AddCommand(gcmd.EncryptCMD)
	root.AddCommand(gcmd.DecryptCMD)
	if err := root.Execute(); err != nil {
		panic(err)
	}
}

AES encryption and decryption

Secrets are never accepted as command-line arguments. -s/--secret has been removed and fails with a migration error. Choose one secret input:

  • --password-file <path|->: password mode. The key is derived with Argon2id (t=3, m=64 MiB, p=4) under a fresh salt, and the output uses a versioned, self-describing format. Trailing CR/LF in the file are removed.
  • --key-file <path|->: raw-key mode. The file holds a hex-encoded 16, 24 or 32-byte key; surrounding whitespace is ignored. The output uses the crypto.AEADEncrypt (AES-GCM) format.
  • Neither flag: on a terminal, you are prompted for the password without echo (encryption asks twice). Without a terminal, the command fails.

Provision secret files outside version control. On Unix they must not be accessible by group or others (chmod 600). - reads the secret from stdin. Keep keys/passwords separate from encrypted data and back up the material required for recovery.

# Password file already provisioned through your secret-management process.
chmod 600 ./pw.txt
gutils encrypt aes -i config.toml --password-file ./pw.txt          # -> config.toml.enc
gutils decrypt aes -i config.toml.enc -o config.restored.toml --password-file ./pw.txt
pass show app/aes | gutils encrypt aes -i config.toml --password-file -

# Raw key: use a private directory and an unused output filename.
# umask protects the key from its initial creation, before chmod.
umask 077
openssl rand -hex 32 > key.hex
chmod 600 key.hex
gutils encrypt aes -i config.toml --key-file key.hex
gutils decrypt aes -i config.toml.enc -o config.restored.toml --key-file key.hex

# Directory mode processes each regular file directly inside the directory.
gutils encrypt aes -i ./configs --password-file ./pw.txt

Password and raw-key commands above illustrate alternative modes. Keep track of which mode produced each ciphertext; running them on the same input name replaces its existing regular .enc output. Never overwrite the only key for existing ciphertext when generating a new key.

Outputs are written with mode 0600 through a temporary file and an atomic rename. An existing symlink (live or dangling), directory or special file at the output path is refused and left untouched. An existing regular file is replaced. Directory mode skips symlinks, special files and names that already end in .enc, and it enforces file-count and byte budgets. It is not recursive and does not accept -o. Password mode derives the key once per directory run. See the output-path safety notes for caller responsibilities.

Files written by the removed encrypt aes -s <password> used the password bytes directly as the AES key. To decrypt them, use --legacy-password-as-key together with a password input, then encrypt them again in password mode:

gutils decrypt aes -i old.enc -o old.txt --password-file ./pw.txt --legacy-password-as-key
gutils encrypt aes -i old.txt --password-file ./pw.txt

See AES formats and limits before migrating stored ciphertext.

Documentation

Overview

Package cmd some useful tools for command argument

Index

Constants

This section is empty.

Variables

View Source
var DecryptAESCMD = &cobra.Command{
	Use:   "aes",
	Short: "decrypt a file written by `encrypt aes`",
	Long: gutils.Dedent(`
		decrypt a file written by "encrypt aes".

		The password-based format is detected by its header. Raw-key files need
		--key-file. Files written by the removed "-s" flag need --password-file (or the
		prompt) together with --legacy-password-as-key.
	`),
	Args: NoExtraArgs,
	RunE: func(cmd *cobra.Command, _ []string) error {
		return runDecryptAES(cmd, &decryptAESArgs)
	},
}

DecryptAESCMD decrypt files by aes

`go run cmd/main/main.go decrypt aes -i cmd/root.go.enc --password-file ./pw.txt`
View Source
var DecryptCMD = &cobra.Command{
	Use:   "decrypt",
	Short: "decrypt file",
	Long: gutils.Dedent(`
		decrypt a file encrypted by "encrypt"

		Run

			go run main.go decrypt aes -i <file>.enc --password-file <path|->
			go run main.go decrypt aes -i <file>.enc --key-file <path|->
			go run main.go decrypt aes -i <file>.enc --password-file <path|-> --legacy-password-as-key
	`),
	Args: NoExtraArgs,
}

DecryptCMD decrypt files

View Source
var EncryptAESCMD = &cobra.Command{
	Use:   "aes",
	Short: "encrypt a file or the files of a directory with AES-256-GCM",
	Long: gutils.Dedent(`
		encrypt a file, or every regular file directly inside a directory, by AES-GCM.

		Password mode (--password-file, or the interactive prompt) derives an AES-256 key
		with Argon2id (t=3, m=64 MiB, p=4) under a fresh random salt and writes a
		self-describing, versioned format. A directory run derives the key once.
		Raw-key mode (--key-file) uses a hex-encoded 16/24/32-byte key directly.

		Outputs are written with mode 0600 via a temporary file and an atomic rename;
		an existing symlink or special file at the output path is refused.
		Directory inputs ending in .enc are included by default. Use --skip-suffix-inputs
		to explicitly exclude them; a suffix alone does not identify encrypted content.
	`),
	Args: NoExtraArgs,
	RunE: func(cmd *cobra.Command, _ []string) error {
		return runEncryptAES(cmd, &encryptAESArgs)
	},
}

EncryptAESCMD encrypt files by aes

`go run cmd/main/main.go encrypt aes -i cmd/root.go --password-file ./pw.txt`
View Source
var EncryptCMD = &cobra.Command{
	Use:   "encrypt",
	Short: "encrypt file or directory",
	Long: gutils.Dedent(`
		encrypt file or directory by aes

		Usage

			import (
				gcmd "github.com/Laisky/go-utils/v6/cmd"
			)

			func init() {
				rootCMD.AddCommand(gcmd.EncryptCMD)
				rootCMD.AddCommand(gcmd.DecryptCMD)
			}

		Run

			go run main.go encrypt aes -i <file_or_dir> --password-file <path|->
			go run main.go encrypt aes -i <file_or_dir> --key-file <path|->
			go run main.go encrypt aes -i <file_or_dir>   # prompts for a password on a terminal
	`),
	Args: NoExtraArgs,
}

EncryptCMD encrypt files

View Source
var RSA = &cobra.Command{
	Use:   "rsa",
	Short: "rsa",
	Args:  NoExtraArgs,
	Run: func(_ *cobra.Command, _ []string) {
	},
}

RSA some rsa command tools

View Source
var RSASign = &cobra.Command{
	Use:   "sign",
	Short: "sign by RSA & SHA256",
	Args:  NoExtraArgs,
	RunE: func(_ *cobra.Command, _ []string) error {
		return errors.Wrap(SignFileByRSA(rsaPrikeyPemFilepath, fileWantToSignature), "sign by rsa")
	},
}

RSASign sign file by rsa

View Source
var RSAVerify = &cobra.Command{
	Use:   "verify",
	Short: "verify by RSA & SHA256",
	Args:  NoExtraArgs,
	RunE: func(_ *cobra.Command, _ []string) error {
		return errors.Wrap(VerifyFileByRSA(rsaPubkeyPemFilepath, fileWantToSignature), "verify by rsa")
	},
}

RSAVerify verify file by rsa

Functions

func Execute

func Execute()

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

func NoExtraArgs

func NoExtraArgs(_ *cobra.Command, args []string) error

NoExtraArgs make sure every args has been processed

do not allow any unprocessed args

Example

use with cobra.Command:

cmd = &cobra.Command{
    Args: NoExtraArgs,
}

func SignFileByRSA

func SignFileByRSA(prikeyPath, filePath string) error

SignFileByRSA sign file by rsa

func VerifyFileByRSA

func VerifyFileByRSA(pubkeyPath, filePath string) error

VerifyFileByRSA verify file by rsa

Types

This section is empty.

Directories

Path Synopsis
Package main gutils' command line tool
Package main gutils' command line tool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址