actions

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Jun 14, 2026 License: Apache-2.0 Imports: 42 Imported by: 0

Documentation

Overview

Package actions provides base functionality for Idsec SDK command line actions.

This package defines the core interfaces and base implementations for creating command line actions in the Idsec SDK. It includes configuration management, flag handling, and common execution patterns that can be shared across different CLI commands.

Package actions provides base implementation for CLI exec actions in the IDSEC SDK.

This package contains the core functionality for defining and executing CLI commands that integrate with various authentication providers and profiles.

Package actions provides base functionality for Idsec SDK command line actions.

This file contains panic recovery logic for the CLI. RecoverFromPanic is intended to be deferred at the top of main() so that any unhandled panic (intentional panic(err) calls, reflection errors, slice-bounds errors, etc.) is caught and presented to the user as a friendly message instead of a raw goroutine stack trace.

Set IDSEC_DEBUG=true to include the full stack trace in the output.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RecoverFromPanic

func RecoverFromPanic()

RecoverFromPanic catches any panic in the current goroutine and prints a user-friendly error message. When IDSEC_DEBUG=true, the full stack trace is printed to stderr. The function calls os.Exit(1) after handling the panic.

Usage — add as the first deferred call in main():

func main() {
    defer actions.RecoverFromPanic()
    // ...
}

Types

type IdsecAction

type IdsecAction interface {
	// DefineAction configures the provided cobra command with action-specific behavior
	DefineAction(cmd *cobra.Command)
}

IdsecAction is an interface that defines the structure for actions in the Idsec SDK.

IdsecAction provides a contract for implementing command line actions that can be integrated with the Idsec SDK CLI framework. Implementations should define their specific command behavior through the DefineAction method.

type IdsecBaseAction

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

IdsecBaseAction is a struct that implements the IdsecAction interface as a base action.

IdsecBaseAction provides common functionality that can be shared across different action implementations. It includes logger management and common flag handling patterns. This struct can be embedded in more specific action implementations to provide consistent behavior across the CLI.

func NewIdsecBaseAction

func NewIdsecBaseAction() *IdsecBaseAction

NewIdsecBaseAction creates a new instance of IdsecBaseAction.

NewIdsecBaseAction initializes a new IdsecBaseAction with a configured logger. The logger is set up with a default configuration using the "IdsecBaseAction" name and Unknown log level.

Returns a new IdsecBaseAction instance ready for use.

Example:

action := NewIdsecBaseAction()
action.CommonActionsConfiguration(cmd)

func (*IdsecBaseAction) CommonActionsConfiguration

func (a *IdsecBaseAction) CommonActionsConfiguration(cmd *cobra.Command)

CommonActionsConfiguration sets up common flags for the command line interface.

CommonActionsConfiguration adds standard persistent flags to the provided cobra command that are commonly used across different Idsec SDK actions. These flags control logging behavior, output formatting, certificate handling, and other common CLI options.

The following flags are added:

  • raw: Controls whether output should be in raw format
  • silent: Enables silent execution without interactive prompts
  • allow-output: Allows stdout/stderr output even in silent mode
  • verbose: Enables verbose logging
  • logger-style: Specifies the style for verbose logging
  • log-level: Sets the log level for verbose mode
  • disable-cert-verification: Disables HTTPS certificate verification (unsafe)
  • trusted-cert: Specifies a trusted certificate for HTTPS calls

Parameters:

  • cmd: The cobra command to configure with persistent flags

Example:

action := NewIdsecBaseAction()
action.CommonActionsConfiguration(rootCmd)

func (*IdsecBaseAction) CommonActionsExecution

func (a *IdsecBaseAction) CommonActionsExecution(cmd *cobra.Command, execArgs []string, printUpgrade bool)

CommonActionsExecution executes common actions based on the command line flags.

CommonActionsExecution processes the standard flags set up by CommonActionsConfiguration and applies the corresponding configuration changes to the Idsec SDK runtime. This function should be called early in command execution to ensure proper setup.

The function performs the following operations:

  1. Sets default states for color, interactivity, logging, and certificates
  2. Processes each flag and applies the corresponding configuration
  3. Handles certificate verification settings (disable or trusted cert)
  4. Configures profile name if provided
  5. Sets default DEPLOY_ENV if not already set

Parameters:

  • cmd: The cobra command containing the parsed flags
  • args: Command line arguments (not currently used but part of cobra pattern)

The function ignores flag parsing errors and uses default values in such cases, following the principle of graceful degradation for CLI flag handling.

Example:

action := NewIdsecBaseAction()
action.CommonActionsExecution(cmd, args, true)

type IdsecBaseExecAction

type IdsecBaseExecAction struct {
	*IdsecBaseAction
	// contains filtered or unexported fields
}

IdsecBaseExecAction provides a base implementation for IDSEC CLI exec actions.

This struct serves as a foundation for implementing specific exec actions by combining the common IDSEC action functionality with exec-specific behavior. It handles profile loading, authentication, and action execution orchestration.

The struct embeds IdsecBaseAction to inherit common CLI functionality and adds exec-specific capabilities like profile management and action delegation.

func NewIdsecBaseExecAction

func NewIdsecBaseExecAction(execAction *IdsecExecAction, name string, profilesLoader *profiles.ProfileLoader) *IdsecBaseExecAction

NewIdsecBaseExecAction creates a new instance of IdsecBaseExecAction with the specified configuration.

NewIdsecBaseExecAction initializes a base exec action with the provided action implementation, name for logging, and profile loader. The returned instance can be used to define and execute CLI commands that require profile-based authentication. The constructor sets up logging with the specified name and configures all necessary dependencies for command execution.

Parameters:

  • execAction: Implementation of the specific exec action behavior
  • name: Identifier used for logging and error reporting
  • profilesLoader: Service for loading and managing authentication profiles

Returns a configured IdsecBaseExecAction ready for command definition and execution.

Example:

action := NewIdsecBaseExecAction(
    &myExecAction,
    "my-action",
    profileLoader,
)
action.DefineAction(rootCmd)

func (*IdsecBaseExecAction) DefineAction

func (a *IdsecBaseExecAction) DefineAction(cmd *cobra.Command)

DefineAction defines the CLI `exec` command structure and configuration.

DefineAction creates and configures the `exec` subcommand with all necessary flags and execution behavior. It sets up the command hierarchy, adds persistent flags for profile management and execution control, and delegates specific action definition to the embedded exec action implementation.

The method configures the following persistent flags:

  • profile-name: Specifies which authentication profile to use
  • output-path: Optional file path for writing command output
  • request-file: Optional file containing action parameters
  • retry-count: Number of retry attempts for failed executions
  • refresh-auth: Forces authentication token refresh
  • page-size: Items per page for interactive paging, pausing between pages (0 = disabled)

Parameters:

  • cmd: The parent cobra command to which the exec command will be added

The method panics if the embedded exec action fails to define its specific behavior.

Example:

baseAction := NewIdsecBaseExecAction(&myAction, "test", loader)
baseAction.DefineAction(rootCmd)

type IdsecCacheAction

type IdsecCacheAction struct {
	// IdsecBaseAction provides common action functionality
	*IdsecBaseAction
}

IdsecCacheAction is a struct that implements the IdsecAction interface for cache management.

IdsecCacheAction provides functionality for managing cache operations in the Idsec SDK CLI. It embeds IdsecBaseAction to inherit common CLI functionality and adds specific cache management commands such as clearing cached profiles and credentials.

The action specifically supports clearing cache for basic keyring implementations, which store credentials and profile information in local files.

func NewIdsecCacheAction

func NewIdsecCacheAction() *IdsecCacheAction

NewIdsecCacheAction creates a new instance of IdsecCacheAction.

NewIdsecCacheAction initializes a new IdsecCacheAction with an embedded IdsecBaseAction, providing all the common CLI functionality along with cache-specific operations. The returned instance is ready to be used for defining cache management commands.

Returns a new IdsecCacheAction instance with initialized base action functionality.

Example:

cacheAction := NewIdsecCacheAction()
cacheAction.DefineAction(rootCmd)

func (*IdsecCacheAction) DefineAction

func (a *IdsecCacheAction) DefineAction(cmd *cobra.Command)

DefineAction defines the CLI cache action and adds cache management subcommands.

DefineAction creates a "cache" command with subcommands for cache management operations. Currently, it provides a "clear" subcommand that removes cached credentials and profile information from the basic keyring implementation.

The function sets up:

  1. A parent "cache" command for cache management
  2. Common action configuration through embedded IdsecBaseAction
  3. A "clear" subcommand for clearing cached data
  4. Persistent pre-run hook for common action execution

Parameters:

  • cmd: The parent cobra command to which the cache command will be added

The cache command supports the standard CLI flags inherited from IdsecBaseAction and executes common action setup before running cache-specific operations.

Example:

cacheAction := NewIdsecCacheAction()
cacheAction.DefineAction(rootCmd)
// This adds: myapp cache clear

type IdsecConfigureAction

type IdsecConfigureAction struct {
	// IdsecBaseAction provides common action functionality
	*IdsecBaseAction
	// contains filtered or unexported fields
}

IdsecConfigureAction is a struct that implements the IdsecAction interface for configuring the CLI profiles.

IdsecConfigureAction provides functionality for managing CLI configuration profiles, including both interactive and silent configuration modes. It handles profile creation, modification, and persistence, as well as configuring authentication profiles for different authenticators supported by the Idsec SDK.

The action supports dynamic flag generation based on available authenticators and their supported authentication methods, allowing for flexible configuration of different authentication backends.

func NewIdsecConfigureAction

func NewIdsecConfigureAction(profilesLoader *profiles.ProfileLoader) *IdsecConfigureAction

NewIdsecConfigureAction creates a new instance of IdsecConfigureAction.

NewIdsecConfigureAction initializes a new IdsecConfigureAction with the provided profile loader and an embedded IdsecBaseAction for common CLI functionality. The profile loader is used for loading existing profiles and saving new or modified profile configurations.

Parameters:

  • profilesLoader: A pointer to a ProfileLoader for handling profile operations

Returns a new IdsecConfigureAction instance ready for defining configure commands.

Example:

loader := profiles.NewProfileLoader()
configAction := NewIdsecConfigureAction(loader)
configAction.DefineAction(rootCmd)

func (*IdsecConfigureAction) DefineAction

func (a *IdsecConfigureAction) DefineAction(cmd *cobra.Command)

DefineAction defines the CLI configure action and adds configuration management commands.

DefineAction creates a "configure" command that allows users to set up and modify CLI profiles for the Idsec SDK. The command supports both interactive and silent modes of operation, dynamically generates flags based on available authenticators, and handles complex profile configuration scenarios.

The function performs the following setup:

  1. Creates a "configure" command with appropriate usage and help text
  2. Sets up common action configuration through embedded IdsecBaseAction
  3. Dynamically generates flags for IdsecProfile struct fields
  4. Iterates through supported authenticators and adds their specific flags
  5. Generates flags for authentication methods and their settings
  6. Handles flag conflicts by filtering duplicate flags

Parameters:

  • cmd: The parent cobra command to which the configure command will be added

The configure command supports extensive flag generation including:

  • Profile-level settings (from models.IdsecProfile)
  • Authenticator enablement flags (work-with-<authenticator>)
  • Authentication method selection flags
  • Authenticator-specific configuration flags
  • Authentication method-specific settings flags

Example:

configAction := NewIdsecConfigureAction(loader)
configAction.DefineAction(rootCmd)
// This adds: myapp configure [flags]

type IdsecExecAction

type IdsecExecAction interface {
	// DefineExecAction configures the specific exec command structure and flags.
	//
	// This method is called during command initialization to set up the CLI command
	// structure, including any subcommands, flags, and help text specific to the action.
	//
	// Parameters:
	//   - cmd: The parent cobra command to which the exec action will be added
	//
	// Returns an error if the command definition fails.
	DefineExecAction(cmd *cobra.Command) error

	// RunExecAction executes the specific action logic with an authenticated API client.
	//
	// This method is called after authentication and profile loading are complete.
	// It receives a fully configured CLI API client and should implement the actual
	// business logic for the specific action.
	//
	// Parameters:
	//   - api: Authenticated IDSEC CLI API client
	//   - cmd: The root command being executed
	//   - execCmd: The specific exec command being run
	//   - args: Command line arguments passed to the action
	//
	// Returns an error if the action execution fails.
	RunExecAction(api *cli.IdsecCLIAPI, cmd *cobra.Command, execCmd *cobra.Command, args []string) error
}

IdsecExecAction defines the interface for executing CLI actions in the IDSEC SDK.

Implementations of this interface provide the actual command definition and execution logic for specific IDSEC SDK operations. The interface enables pluggable action implementations while maintaining consistent command structure and behavior.

type IdsecLoginAction

type IdsecLoginAction struct {
	*IdsecBaseAction
	// contains filtered or unexported fields
}

IdsecLoginAction is a struct that implements the IdsecAction interface for login action.

IdsecLoginAction provides authentication functionality for the Idsec SDK CLI. It handles user authentication across multiple authentication methods and manages token storage and retrieval. The action supports interactive and non-interactive modes, shared secrets between authenticators, token refresh, and forced re-authentication.

Key features:

  • Multi-authenticator support (e.g., ISP, identity providers)
  • Interactive credential prompting with shared secrets
  • Token caching and refresh capabilities
  • Force login and token display options
  • Profile-based configuration management

func NewIdsecLoginAction

func NewIdsecLoginAction(profilesLoader *profiles.ProfileLoader) *IdsecLoginAction

NewIdsecLoginAction creates a new instance of IdsecLoginAction.

NewIdsecLoginAction initializes a new IdsecLoginAction with the provided profile loader for managing authentication profiles. The action inherits common functionality from IdsecBaseAction and configures profile-specific behavior.

Parameters:

  • profilesLoader: A ProfileLoader interface for loading and managing authentication profiles

Returns a new IdsecLoginAction instance ready for CLI integration.

Example:

loader := profiles.DefaultProfilesLoader()
action := NewIdsecLoginAction(loader)
action.DefineAction(rootCmd)

func (*IdsecLoginAction) DefineAction

func (a *IdsecLoginAction) DefineAction(cmd *cobra.Command)

DefineAction defines the CLI `login` action, and adds the login function.

DefineAction configures the login command with all necessary flags and behavior for authentication operations. The command supports various authentication options including profile selection, forced login, shared secrets management, token display, and refresh capabilities.

Command flags added:

  • profile-name: Specifies which profile to use for authentication
  • force: Forces login even if valid tokens exist
  • no-shared-secrets: Disables credential sharing between authenticators
  • show-tokens: Displays authentication tokens in output
  • refresh-auth: Attempts to refresh existing tokens from cache
  • [authenticator]-username: Username for specific authenticators
  • [authenticator]-secret: Secret/password for specific authenticators

Parameters:

  • cmd: The parent cobra command to attach the login command to

The login command will be added as a subcommand with all configured flags and will execute the authentication workflow when invoked.

Example:

action := NewIdsecLoginAction(loader)
action.DefineAction(rootCmd)
// Now 'idsec login' command is available

type IdsecProfilesAction

type IdsecProfilesAction struct {
	// IdsecBaseAction provides common action functionality
	*IdsecBaseAction
	// contains filtered or unexported fields
}

IdsecProfilesAction is a struct that implements the IdsecAction interface for managing CLI profiles.

IdsecProfilesAction provides functionality for managing multiple CLI configuration profiles including listing, showing, deleting, clearing, cloning, adding, and editing profiles. It handles profile operations through a ProfileLoader and provides both interactive and non-interactive modes for various operations.

The action supports comprehensive profile management operations:

  • List profiles with optional filtering by name pattern or auth type
  • Show detailed profile information
  • Delete specific profiles with confirmation prompts
  • Clear all profiles with confirmation
  • Clone profiles with automatic or custom naming
  • Add profiles from file paths
  • Edit profiles interactively using an external editor

func NewIdsecProfilesAction

func NewIdsecProfilesAction(profilesLoader *profiles.ProfileLoader) *IdsecProfilesAction

NewIdsecProfilesAction creates a new instance of IdsecProfilesAction.

NewIdsecProfilesAction initializes a new IdsecProfilesAction with the provided profile loader and an embedded IdsecBaseAction for common CLI functionality. The profile loader is used for all profile operations including loading, saving, deleting, and managing profile configurations.

Parameters:

  • profilesLoader: A pointer to a ProfileLoader for handling profile operations

Returns a new IdsecProfilesAction instance ready for defining profile management commands.

Example:

loader := profiles.NewProfileLoader()
profilesAction := NewIdsecProfilesAction(loader)
profilesAction.DefineAction(rootCmd)

func (*IdsecProfilesAction) DefineAction

func (a *IdsecProfilesAction) DefineAction(cmd *cobra.Command)

DefineAction defines the CLI profiles action and adds profile management commands.

DefineAction creates a "profiles" command that provides comprehensive profile management functionality. The command includes multiple subcommands for different profile operations, each with their own flags and functionality.

The function creates the following subcommands:

  • list: Lists all profiles with optional filtering by name pattern or auth type
  • show: Shows detailed information for a specific profile
  • delete: Deletes a specific profile with confirmation
  • clear: Clears all profiles with confirmation
  • clone: Clones an existing profile with optional renaming
  • add: Adds a profile from a file path
  • edit: Opens a profile for interactive editing

Parameters:

  • cmd: The parent cobra command to which the profiles command will be added

Each subcommand includes appropriate flags for configuration and supports both interactive and non-interactive modes where applicable.

Example:

profilesAction := NewIdsecProfilesAction(loader)
profilesAction.DefineAction(rootCmd)
// This adds: myapp profiles [list|show|delete|clear|clone|add|edit] [flags]

type IdsecServiceExecAction

type IdsecServiceExecAction struct {
	// IdsecExecAction interface for execution capabilities
	IdsecExecAction
	// IdsecBaseExecAction provides common execution functionality
	*IdsecBaseExecAction
}

IdsecServiceExecAction is a struct that implements the IdsecExecAction interface for executing service actions.

IdsecServiceExecAction provides functionality for dynamically executing service actions based on service action definitions. It handles the parsing of command-line flags, schema validation, method invocation, and output serialization for service operations.

The action supports:

  • Dynamic command generation from service action definitions
  • Complex type parsing for JSON and array inputs
  • Flag validation with choices and required field checking
  • Method reflection and invocation on service APIs
  • Multiple output format serialization (JSON, primitive types, channels)
  • Request file input support for complex payloads

func NewIdsecServiceExecAction

func NewIdsecServiceExecAction(profilesLoader *profiles.ProfileLoader) *IdsecServiceExecAction

NewIdsecServiceExecAction creates a new instance of IdsecServiceExecAction.

NewIdsecServiceExecAction initializes a new IdsecServiceExecAction with the provided profile loader and embedded IdsecBaseExecAction for common execution functionality. The action is configured with reflection-based method invocation capabilities for dynamic service action execution.

Parameters:

  • profilesLoader: A pointer to a ProfileLoader for handling profile operations

Returns a new IdsecServiceExecAction instance ready for defining and executing service commands.

Example:

loader := profiles.NewProfileLoader()
serviceExecAction := NewIdsecServiceExecAction(loader)
serviceExecAction.DefineExecAction(rootCmd)

func (*IdsecServiceExecAction) DefineExecAction

func (s *IdsecServiceExecAction) DefineExecAction(cmd *cobra.Command) error

DefineExecAction defines the execution actions for all supported service operations.

DefineExecAction processes all supported service action definitions and creates the corresponding cobra command hierarchy for service execution. It iterates through the available service actions and creates the complete command structure for dynamic service operation execution.

Parameters:

  • cmd: The parent cobra command to add service execution commands to

Returns an error if any service action definition processing fails.

The function handles:

  • Processing all supported service actions from the services package
  • Creating command hierarchies for each service action through defineServiceExecActions
  • Error propagation from nested action processing

Example:

err := serviceExecAction.DefineExecAction(rootCmd)
// This adds all supported service commands to rootCmd

func (*IdsecServiceExecAction) RunExecAction

func (s *IdsecServiceExecAction) RunExecAction(api *cli.IdsecCLIAPI, cmd *cobra.Command, execCmd *cobra.Command, execArgs []string) error

RunExecAction executes a service action using reflection-based method invocation.

RunExecAction processes the command hierarchy to determine the target service and action, then uses reflection to locate and invoke the appropriate method on the API service. It handles flag parsing, schema validation, method resolution, and output formatting for dynamic service action execution.

Parameters:

  • api: The IdsecCLIAPI instance containing the service methods
  • cmd: The cobra command being executed
  • execCmd: The parent execution command for context
  • execArgs: Command line arguments for the execution

Returns an error if service resolution, method invocation, or parameter processing fails.

The function handles:

  • Service path resolution from command hierarchy
  • Method name transformation and case-insensitive lookup
  • Schema resolution from service action definitions
  • Flag parsing and validation against schema constraints
  • Request file input for complex payloads
  • Method invocation with appropriate parameters
  • Result serialization and output formatting

Example:

err := serviceExecAction.RunExecAction(api, cmd, execCmd, args)
// Executes the service method and displays formatted output

type IdsecUpgradeAction

type IdsecUpgradeAction struct {
	// IdsecBaseAction provides common action functionality
	*IdsecBaseAction
}

IdsecUpgradeAction is a struct that implements the IdsecAction interface for upgrading the CLI / SDK.

IdsecUpgradeAction provides functionality for managing cache operations in the Idsec SDK CLI. It embeds IdsecBaseAction to inherit common CLI functionality and adds specific upgrade actions.

func NewIdsecUpgradeAction

func NewIdsecUpgradeAction() *IdsecUpgradeAction

NewIdsecUpgradeAction creates a new instance of IdsecUpgradeAction.

NewIdsecCacheAction initializes a new IdsecUpgradeAction with an embedded IdsecBaseAction, providing all the common CLI functionality along with cache-specific operations. The returned instance is ready to be used for defining upgrade commands.

Returns a new IdsecUpgradeAction instance with initialized base action functionality.

Example:

upgradeAction := NewIdsecUpgradeAction()
upgradeAction.DefineAction(rootCmd)

func (*IdsecUpgradeAction) DefineAction

func (a *IdsecUpgradeAction) DefineAction(cmd *cobra.Command)

DefineAction defines the upgrade command and its configuration.

DefineAction creates and configures the "upgrade" command with its flags and subcommands. It sets up the command structure, persistent flags for dry-run and version specification, and integrates with the common actions framework for consistent CLI behavior.

Parameters:

  • cmd: The parent cobra.Command to which the upgrade command will be added

The method configures the following flags:

  • --dry-run: Boolean flag to perform a dry run without actual upgrade
  • --version: String flag to specify a particular version to upgrade to (default: latest)

Example:

rootCmd := &cobra.Command{Use: "idsec"}
upgradeAction := NewIdsecUpgradeAction()
upgradeAction.DefineAction(rootCmd)

type IdsecVersionAction added in v0.3.2

type IdsecVersionAction struct {
	// IdsecBaseAction provides common action functionality
	*IdsecBaseAction
}

IdsecVersionAction is a struct that implements the IdsecAction interface for printing the CLI version.

IdsecVersionAction provides functionality for printing the build version and associated metadata (build number, build date, git commit and git branch) embedded into the Idsec CLI binary. It embeds IdsecBaseAction to inherit common CLI functionality and adds a single "version" command that reports the build information populated at compile time.

func NewIdsecVersionAction added in v0.3.2

func NewIdsecVersionAction() *IdsecVersionAction

NewIdsecVersionAction creates a new instance of IdsecVersionAction.

NewIdsecVersionAction initializes a new IdsecVersionAction with an embedded IdsecBaseAction, providing all the common CLI functionality along with version-specific operations. The returned instance is ready to be used for defining the version command.

Returns a new IdsecVersionAction instance with initialized base action functionality.

Example:

versionAction := NewIdsecVersionAction()
versionAction.DefineAction(rootCmd)

func (*IdsecVersionAction) DefineAction added in v0.3.2

func (a *IdsecVersionAction) DefineAction(cmd *cobra.Command)

DefineAction defines the version command and its configuration.

DefineAction creates and configures the "version" command with a single boolean flag controlling output formatting and attaches it to the parent command.

Parameters:

  • cmd: The parent cobra.Command to which the version command will be added

The method configures the following flags:

  • --silent / -s: Boolean flag to print only the raw semantic version string (e.g. "0.3.1"), without the "Idsec " or leading "v" prefix

Example:

rootCmd := &cobra.Command{Use: "idsec"}
versionAction := NewIdsecVersionAction()
versionAction.DefineAction(rootCmd)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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