cli

package
v0.1.0-alpha.1 Latest Latest
Warning

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

 Go to latest Published: May 10, 2026 License: BSD-3-Clause Imports: 40 Imported by: 0

Documentation

Overview

Package cli holds the kasapi-cli root command, global flags, and the shared output renderers (json / yaml / table).

The package is the outermost adapter on top of internal/api, internal/auth and internal/config: subcommands (added with #7+) translate flags and args into use-case calls and feed the typed result to a Renderer chosen by the global --output flag.

See issue #12.

Index

Constants

View Source 
const (
	ExitOK        = 0
	ExitUserError = 1
	ExitAPIError  = 2
)

Exit codes used by the kasapi-cli binary. They follow the convention declared in issue #12: 0 success, 1 user error (bad flags, bad config, missing file), 2 API error (KAS fault, network failure).

View Source 
const DefaultFormat = FormatTable

DefaultFormat is what --output defaults to when the flag is unset.

Variables

View Source 
var AllFormats = []Format{FormatJSON, FormatYAML, FormatTable}

AllFormats is the canonical, ordered list of accepted --output values. Used by the root command help text and validation.

View Source 
var ErrTableNotSupported = errors.New("table output not supported for this command (try --output=json or --output=yaml)")

ErrTableNotSupported is returned by Render when --output=table is requested for a value that does not implement Tabular.

Functions

func BuildAPIClient 

func BuildAPIClient(opts *RootOptions) (*api.Client, error)

BuildAPIClient resolves credentials from config + env + flags and returns an *api.Client wired with a fresh transport and a token source matching the requested auth_type.

auth_type=plain → credentials are passed verbatim to KasApi each call via api.StaticTokenSource. KasAuth is not contacted; --otp, --session-lifetime, and --session-update-lifetime are therefore not supported in this mode (these are KasAuth-only parameters). auth_type=session → the configured AuthData is treated as the account password; auth.SessionTokenSource fetches a 40-char session token from KasAuth on first use (forwarding --otp, --session-lifetime, and --session-update-lifetime when set) and refreshes it transparently after no_auth / unknown_session faults.

Errors are wrapped as *ExitError with ExitUserError so cmd/kasapi-cli surfaces them with the expected exit code.

func CodeFor 

func CodeFor(err error) int

CodeFor returns the documented exit code for err. *ExitError values carry their own code; any other non-nil error defaults to ExitAPIError since user-input validation should always produce an *ExitError.

func Confirm 

func Confirm(in io.Reader, out io.Writer, prompt string) (bool, error)

Confirm prompts the user on out with prompt + " y/N: " and reads a reply from in. It returns true only on an explicit "y" or "yes" (case-insensitive); empty input or any other string returns false.

Confirm is intended for destructive write operations (#13). When the global --yes flag is set, callers should skip the prompt entirely rather than feeding the answer through this helper.

func NewAccountCmd 

func NewAccountCmd(opts *RootOptions) *cobra.Command

NewAccountCmd returns the "kasapi-cli accounts" subcommand tree: list and get (both get_accounts, the latter with an account_login filter), settings (get_accountsettings), and resources (get_accountresources).

func NewConfigCmd 

func NewConfigCmd(opts *RootOptions) *cobra.Command

NewConfigCmd returns the "kasapi-cli config" subcommand tree: init (interactive bootstrap), show (resolved effective config with auth_data redacted), and path (resolved config-file path).

func NewCronjobsCmd 

func NewCronjobsCmd(opts *RootOptions) *cobra.Command

NewCronjobsCmd returns the "kasapi-cli cronjobs" subcommand tree: list (get_cronjobs, no filter) and get <cronjob-id> (get_cronjobs with a cronjob_id filter).

func NewDDNSUsersCmd 

func NewDDNSUsersCmd(opts *RootOptions) *cobra.Command

NewDDNSUsersCmd returns the "kasapi-cli ddnsusers" subcommand tree: list (get_ddnsusers, no filter) and get <dyndns-login> (get_ddnsusers with a ddns_login filter — note the wire-side asymmetry: the filter parameter has no `y`, unlike the response keys which use the dyndns_ prefix; per the KAS docs at get-ddnsusers-inc.html).

func NewDNSCmd 

func NewDNSCmd(opts *RootOptions) *cobra.Command

NewDNSCmd returns the "kasapi-cli dns" subcommand tree: list --domain <d> [--nameserver <ns>] (get_dns_settings).

func NewDatabasesCmd 

func NewDatabasesCmd(opts *RootOptions) *cobra.Command

NewDatabasesCmd returns the "kasapi-cli databases" subcommand tree: list (get_databases, no filter) and get <database-login> (get_databases with a database_login filter).

func NewDirectoryProtectionCmd 

func NewDirectoryProtectionCmd(opts *RootOptions) *cobra.Command

NewDirectoryProtectionCmd returns the "kasapi-cli directoryprotection" subcommand tree. The KAS endpoint `get_directoryprotection` returns one entry per (path, user) tuple, so a directory with N users surfaces as N rows; for that reason this resource is exposed as a list with an optional `--path` filter rather than the usual list+get pair.

func NewDomainsCmd 

func NewDomainsCmd(opts *RootOptions) *cobra.Command

NewDomainsCmd returns the "kasapi-cli domains" subcommand tree: list (get_domains), get (get_domains with domain_name).

func NewFTPUsersCmd 

func NewFTPUsersCmd(opts *RootOptions) *cobra.Command

NewFTPUsersCmd returns the "kasapi-cli ftpusers" subcommand tree: list (get_ftpusers, no filter) and get <ftp-login> (get_ftpusers with an ftp_login filter).

func NewGenDocsCmd 

func NewGenDocsCmd() *cobra.Command

NewGenDocsCmd returns the hidden "kasapi-cli gen-docs <out-dir>" subcommand. It walks the assembled command tree (cmd.Root()) and writes one Markdown file per command into <out-dir> using cobra/doc.GenMarkdownTree, so docs/cli/ stays in sync with the actual flag and subcommand surface.

DisableAutoGenTag is set on the root before generation so the output is reproducible — without it cobra appends a per-run timestamp to every file and `make docs` produces churn even when the CLI surface has not changed.

func NewMailCmd 

func NewMailCmd(opts *RootOptions) *cobra.Command

NewMailCmd returns the "kasapi-cli mail" subcommand tree, grouping the mail-related read endpoints (mail accounts; later forwards, filters, mailing lists).

func NewSambaUsersCmd 

func NewSambaUsersCmd(opts *RootOptions) *cobra.Command

NewSambaUsersCmd returns the "kasapi-cli sambausers" subcommand tree: list (get_sambausers, no filter) and get <samba-login> (get_sambausers with a samba_login filter).

func NewServerCmd 

func NewServerCmd(opts *RootOptions) *cobra.Command

NewServerCmd returns the "kasapi-cli server" subcommand tree. For now it carries a single child, "info" (get_server_information).

func NewSoftwareInstallsCmd 

func NewSoftwareInstallsCmd(opts *RootOptions) *cobra.Command

NewSoftwareInstallsCmd returns the "kasapi-cli softwareinstalls" subcommand tree: list (get_softwareinstall, no filter) and get <software-id> (get_softwareinstall with a software_id filter). The KAS action is singular for both variants.

func NewSubdomainsCmd 

func NewSubdomainsCmd(opts *RootOptions) *cobra.Command

NewSubdomainsCmd returns the "kasapi-cli subdomains" subcommand tree: list (get_subdomains), get (get_subdomains with subdomain_name).

func NewTLDsCmd 

func NewTLDsCmd(opts *RootOptions) *cobra.Command

NewTLDsCmd returns the "kasapi-cli tlds" subcommand tree: list (get_topleveldomains).

func NewUsageCmd 

func NewUsageCmd(opts *RootOptions) *cobra.Command

NewUsageCmd returns the "kasapi-cli usage" subcommand tree: space (get_space), space-detail (get_space_usage), traffic (get_traffic).

func Render 

func Render(w io.Writer, format Format, v any) error

Render writes v to w in the requested format. For FormatTable the value must implement Tabular; otherwise Render returns an error so callers can surface it as a user error.

Types

type ExitError 

type ExitError struct {
	Code int
	Err  error
}

ExitError carries an exit code alongside the underlying error so the binary entry point can translate failures to the documented codes. Use UserError or APIError to construct one; falling through with a raw error from a subcommand maps to ExitAPIError by convention.

func APIError 

func APIError(err error, msg string) *ExitError

APIError wraps err as an ExitError with ExitAPIError.

func UserError 

func UserError(err error, msg string) *ExitError

UserError wraps err as an ExitError with ExitUserError. msg is optional; when non-empty it is prepended to the underlying message.

func (*ExitError) Error 

func (e *ExitError) Error() string

func (*ExitError) Unwrap 

func (e *ExitError) Unwrap() error

type Format 

type Format string

Format identifies an output renderer chosen via --output. 

const (
	FormatJSON  Format = "json"
	FormatYAML  Format = "yaml"
	FormatTable Format = "table"
)

Output formats accepted by --output. AllFormats is the canonical ordered listing; DefaultFormat is what an unset --output resolves to.

func ParseFormat 

func ParseFormat(s string) (Format, error)

ParseFormat returns the Format matching s or an error listing valid values. The empty string maps to DefaultFormat.

type RootOptions 

type RootOptions struct {
	ConfigPath string
	Profile    string
	Login      string
	AuthData   string
	AuthType   string
	OTP        string

	SessionLifetime       int
	SessionUpdateLifetime string

	OutputRaw string
	Output    Format

	NoColor bool
	Verbose bool
	Yes     bool
}

RootOptions captures the values bound to the root command's persistent flags. Subcommands read it to obtain credentials, configuration paths, and the chosen output format.

Output is parsed from the raw --output string in PersistentPreRunE so invalid values are rejected before any subcommand runs.

func NewRootCmd 

func NewRootCmd() (*cobra.Command, *RootOptions)

NewRootCmd builds the kasapi-cli root command and registers all persistent global flags on it. Subcommands are registered by callers (cmd/kasapi-cli) so the cli package does not import every resource package directly.

The returned *RootOptions is updated in place by cobra as flags are parsed; subcommands receive it through closure capture or by reading it back from cmd.Context().

type Tabular 

type Tabular interface {
	TableHeaders() []string
	TableRows() [][]string
}

Tabular is implemented by values that can render themselves as a fixed-column table. Subcommand result types satisfy it so --output=table works without per-renderer special cases.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.