cli

Documentation

Index

• Constants
• Variables
• func Main(version, buildTime, gitCommit string)
• func RandomName() string
• func Signals()
• type CLI
• type Engine
• type Handler
• type Help
• type Options
• type Runner
  • func NewRunner() *Runner
  • func (r *Runner) Dispatch(command string, help *Help, fn Handler)
  • func (r *Runner) Execute(command string, args ...string) error
  • func (r *Runner) Help(out io.Writer, topic string) error
  • func (r *Runner) PrintUsage(w io.Writer, topic string)
  • func (r *Runner) Usage(topic string) error
• type TokenStatus
  • func (t TokenStatus) MarshalJSON() ([]byte, error)
  • func (t TokenStatus) String() string
• type UsageError
  • func (e *UsageError) Error() string

Constants

const (
	DestructiveCommand    string = "@R"
	NonDestructiveCommand string = "@G"
	AdministrativeCommand string = "@W"
	MiscellaneousCommand  string = "@W"
	HiddenCommand         string = "HIDEME"
)

const EngineEnvVar = "SAFE_ENGINE"

EngineEnvVar names the environment variable that sets a default engine preference, for users who want OpenBao without passing --engine every time.

Variables

var (
	Version   string
	BuildTime string
	GitCommit string
)

Build metadata, populated by Main from values the main package receives via -ldflags. Empty in plain `go build` and `go test` runs.

var Adjectives []string

var ErrNoSuchTopic = errors.New("no such help topic")

ErrNoSuchTopic is what Help gives back when it is asked for a topic that was never registered.

var Nouns []string

Functions

func Main

func Main(version, buildTime, gitCommit string)

func RandomName

func RandomName() string

func Signals

func Signals()

Types

type CLI

type CLI struct {
	// contains filtered or unexported fields
}

CLI carries the parsed options and command runner shared by all command handlers. Each handler is a method on *CLI.

type Engine

type Engine interface {
	// Name is the engine's canonical short name, as accepted by --engine.
	Name() string
	// Title is the engine's proper name, for use in messages to the user.
	Title() string
	// Binary is the absolute path to the resolved executable.
	Binary() string
}

Engine is a Vault-compatible server binary that safe can drive: HashiCorp Vault, or OpenBao, which forked from it and keeps the same server, secrets, auth, and operator command surface.

type Handler

type Handler func(command string, args ...string) error

type Help

type Help struct {
	Summary     string
	Usage       string
	Description string
	Type        string
}

type Options

type Options struct {
	Insecure     bool `cli:"-k, --insecure"`
	Version      bool `cli:"-v, --version"`
	Help         bool `cli:"-h, --help"`
	Clobber      bool `cli:"--clobber, --no-clobber"`
	SkipIfExists bool
	Quiet        bool `cli:"--quiet"`

	// Behavour of -T must chain through -- separated commands.  There is code
	// that relies on this.  Will default to $SAFE_TARGET if it exists, or
	// the current safe target otherwise.
	UseTarget string `cli:"-T, --target" env:"SAFE_TARGET"`

	HelpCommand     struct{} `cli:"help"`
	CommandsCommand struct{} `cli:"commands"`
	VersionCommand  struct{} `cli:"version"`

	Envvars struct{} `cli:"envvars"`
	Targets struct {
		JSON bool `cli:"--json"`
	} `cli:"targets"`

	Status struct {
		ErrorIfSealed bool `cli:"-e, --err-sealed"`
	} `cli:"status"`

	Unseal struct{} `cli:"unseal"`
	Seal   struct{} `cli:"seal"`
	Env    struct {
		ForBash bool `cli:"--bash"`
		ForFish bool `cli:"--fish"`
		ForJSON bool `cli:"--json"`
	} `cli:"env"`

	Auth struct {
		Path string `cli:"-p, --path"`
		JSON bool   `cli:"--json"`
	} `cli:"auth, login"`

	Logout struct{} `cli:"logout"`
	Renew  struct{} `cli:"renew"`
	Ask    struct{} `cli:"ask"`
	Set    struct{} `cli:"set, write"`
	Paste  struct{} `cli:"paste"`
	Exists struct{} `cli:"exists, check"`

	Local struct {
		As       string   `cli:"--as"`
		File     string   `cli:"-f, --file"`
		Memory   bool     `cli:"-m, --memory"`
		Port     int      `cli:"-p, --port"`
		Config   []string `cli:"-c, --config"`
		Listener []string `cli:"-l, --listener"`
		Engine   string   `cli:"-e, --engine"`
	} `cli:"local"`

	Init struct {
		Single    bool `cli:"-s, --single"`
		NKeys     int  `cli:"--keys"`
		Threshold int  `cli:"--threshold"`
		JSON      bool `cli:"--json"`
		Sealed    bool `cli:"--sealed"`
		NoMount   bool `cli:"--no-mount"`
		Persist   bool `cli:"--persist, --no-persist"`
	} `cli:"init"`

	Rekey struct {
		NKeys     int      `cli:"--keys, --num-unseal-keys"`
		Threshold int      `cli:"--threshold, --keys-to-unseal"`
		GPG       []string `cli:"--gpg"`
		Persist   bool     `cli:"--persist, --no-persist"`
	} `cli:"rekey"`

	Get struct {
		KeysOnly bool `cli:"--keys"`
		Yaml     bool `cli:"--yaml"`
	} `cli:"get, read, cat"`

	Versions struct{} `cli:"versions,revisions"`

	List struct {
		Single bool `cli:"-1"`
		Quick  bool `cli:"-q, --quick"`
	} `cli:"ls"`

	Paths struct {
		ShowKeys bool `cli:"--keys"`
		Quick    bool `cli:"-q, --quick"`
		Exact    bool `cli:"--exact"`
	} `cli:"paths"`

	Tree struct {
		ShowKeys   bool `cli:"--keys"`
		HideLeaves bool `cli:"-d, --hide-leaves"`
		Quick      bool `cli:"-q, --quick"`
		Exact      bool `cli:"--exact"`
	} `cli:"tree"`

	Values struct {
		ShowKeys    bool     `cli:"--keys"`
		AllVersions bool     `cli:"-a, --all-versions"`
		Deleted     bool     `cli:"-d, --deleted"`
		Paths       []string `cli:"-p, --path"`
	} `cli:"values"`

	Target struct {
		JSON        bool     `cli:"--json"`
		Interactive bool     `cli:"-i, --interactive"`
		Strongbox   bool     `cli:"-s, --strongbox, --no-strongbox"`
		CACerts     []string `cli:"--ca-cert"`
		Namespace   string   `cli:"-n, --namespace"`

		Delete struct{} `cli:"delete, rm"`
	} `cli:"target"`

	Delete struct {
		Recurse bool `cli:"-R, -r, --recurse"`
		Force   bool `cli:"-f, --force"`
		Destroy bool `cli:"-D, -d, --destroy"`
		All     bool `cli:"-a, --all"`
	} `cli:"delete, rm"`

	Undelete struct {
		All bool `cli:"-a, --all"`
	} `cli:"undelete, unrm, urm"`

	Revert struct {
		Deleted bool `cli:"-d, --deleted"`
	} `cli:"revert"`

	Export struct {
		All     bool `cli:"-a, --all"`
		Deleted bool `cli:"-d, --deleted"`
		//These do nothing but are kept for backwards-compat
		OnlyAlive bool `cli:"-o, --only-alive"`
		Shallow   bool `cli:"-s, --shallow"`
	} `cli:"export"`

	Import struct {
		IgnoreDestroyed bool `cli:"-I, --ignore-destroyed"`
		IgnoreDeleted   bool `cli:"-i, --ignore-deleted"`
		Shallow         bool `cli:"-s, --shallow"`
	} `cli:"import"`

	Move struct {
		Recurse bool `cli:"-R, -r, --recurse"`
		Force   bool `cli:"-f, --force"`
		Deep    bool `cli:"-d, --deep"`
	} `cli:"move, rename, mv"`

	Copy struct {
		Recurse bool `cli:"-R, -r, --recurse"`
		Force   bool `cli:"-f, --force"`
		Deep    bool `cli:"-d, --deep"`
	} `cli:"copy, cp"`

	Gen struct {
		Policy string `cli:"-p, --policy"`
		Length int    `cli:"-l, --length"`
	} `cli:"gen, auto, generate"`

	SSH     struct{} `cli:"ssh"`
	RSA     struct{} `cli:"rsa"`
	DHParam struct{} `cli:"dhparam, dhparams, dh"`
	Prompt  struct{} `cli:"prompt"`
	Vault   struct{} `cli:"vault!"`
	Fmt     struct {
		Cost int `cli:"--cost"`
	} `cli:"fmt"`

	Curl struct {
		DataOnly bool `cli:"--data-only"`
	} `cli:"curl"`

	UUID   struct{} `cli:"uuid"`
	Option struct{} `cli:"option"`

	X509 struct {
		Validate struct {
			CA         bool     `cli:"-A, --ca"`
			SignedBy   string   `cli:"-i, --signed-by"`
			NotRevoked bool     `cli:"-R, --not-revoked"`
			Revoked    bool     `cli:"-r, --revoked"`
			NotExpired bool     `cli:"-E, --not-expired"`
			Expired    bool     `cli:"-e, --expired"`
			Name       []string `cli:"-n, --for"`
			Bits       []int    `cli:"-b, --bits"`
		} `cli:"validate, check"`

		Issue struct {
			CA           bool     `cli:"-A, --ca"`
			Subject      string   `cli:"-s, --subj, --subject"`
			Type         string   `cli:"--type"`
			Bits         int      `cli:"-b, --bits"`
			Curve        string   `cli:"--curve"`
			SignedBy     string   `cli:"-i, --signed-by"`
			Name         []string `cli:"-n, --name"`
			TTL          string   `cli:"-t, --ttl"`
			KeyUsage     []string `cli:"-u, --key-usage"`
			SigAlgorithm string   `cli:"-l, --sig-algorithm"`
		} `cli:"issue"`

		Revoke struct {
			SignedBy string `cli:"-i, --signed-by"`
		} `cli:"revoke"`

		Renew struct {
			Subject      string   `cli:"-s, --subj, --subject"`
			Name         []string `cli:"-n, --name"`
			SignedBy     string   `cli:"-i, --signed-by"`
			TTL          string   `cli:"-t, --ttl"`
			KeyUsage     []string `cli:"-u, --key-usage"`
			SigAlgorithm string   `cli:"-l, --sig-algorithm"`
		} `cli:"renew"`

		Reissue struct {
			Subject      string   `cli:"-s, --subj, --subject"`
			Name         []string `cli:"-n, --name"`
			Type         string   `cli:"--type"`
			Bits         int      `cli:"-b, --bits"`
			Curve        string   `cli:"--curve"`
			SignedBy     string   `cli:"-i, --signed-by"`
			TTL          string   `cli:"-t, --ttl"`
			KeyUsage     []string `cli:"-u, --key-usage"`
			SigAlgorithm string   `cli:"-l, --sig-algorithm"`
		} `cli:"reissue"`

		Show struct {
		} `cli:"show"`

		CRL struct {
			Renew bool `cli:"--renew"`
		} `cli:"crl"`
	} `cli:"x509"`
}

type Runner

type Runner struct {
	Handlers map[string]Handler
	Topics   map[string]*Help
}

func NewRunner

func NewRunner() *Runner

func (*Runner) Dispatch

func (r *Runner) Dispatch(command string, help *Help, fn Handler)

func (*Runner) Execute

func (r *Runner) Execute(command string, args ...string) error

func (*Runner) Help

func (r *Runner) Help(out io.Writer, topic string) error

Help writes the topic to out. A topic it does not have is reported back rather than complained about here: what to say about it, and where, belongs to the caller, and ending the process from inside the lookup skipped the cleanup safe does on its way out.

func (*Runner) PrintUsage

func (r *Runner) PrintUsage(w io.Writer, topic string)

PrintUsage writes the usage block for topic to w. It does not exit.

func (*Runner) Usage

func (r *Runner) Usage(topic string) error

Usage returns a UsageError for topic.

type TokenStatus

type TokenStatus struct {
	// contains filtered or unexported fields
}

func (TokenStatus) MarshalJSON

func (t TokenStatus) MarshalJSON() ([]byte, error)

func (TokenStatus) String

func (t TokenStatus) String() string

type UsageError

type UsageError struct {
	Topic string
}

UsageError signals a command was invoked incorrectly. Handlers return it instead of exiting; the CLI renders the topic's usage block via PrintUsage and exits non-zero. Returning rather than calling os.Exit keeps the dispatch layer testable.

func (*UsageError) Error

func (e *UsageError) Error() string