Setup

Setup Class

class Setup(config: ConfigManager, ui_config: UIConfigManager, plist_manager: PropertylistManager)

Handles the initial setup process for the Patcher CLI tool.

This class guides users through configuring the necessary components to integrate with their Jamf environment. The setup includes creating API roles, clients, and configuring user interface settings for PDF reports.

Parameters:

• config (ConfigManager) – Manages application configuration, including credential storage.

• ui_config (UIConfigManager) – Handles UI-related configurations for the setup process.

• plist_manager (PropertylistManager) – Handles read/write operations to project property list.

property completed: bool

Indicates whether the setup process has been completed.

Returns:

True if setup has been completed, False otherwise.

Return type:

bool

async prompt_credentials(setup_type: SetupType) → dict

Prompt for credentials based on the credential type.

Parameters:

setup_type (SetupType) – The SetupType of credentials to prompt for.

Returns:

The credentials in dictionary form.

Return type:

dict

async prompt_ui_settings() → None

Drive the interactive UI configuration prompts (header/footer text, font, logo, header color) and persist them via the UIConfigManager. Triggers font downloads on first run.

Replaces the legacy UIConfigManager.setup_ui method, moved to the CLI layer so the core UI config object stays free of asyncclick and PIL dependencies for library callers.

Return type:

None

async prompt_font_config() → dict[str, str]

Prompt for custom font paths and copy them into Patcher’s font directory.

Returns:

A dictionary containing the font name, regular font path, and bold font path.

Return type:

dict[str, str]

async prompt_logo_config() → str

Prompt for a logo file path, validate it as an image, and copy it into Patcher’s Application Support directory.

Returns:

The path to the saved logo file.

Return type:

str

Raises:

• SetupError – If the provided logo path does not exist.

• PatcherError – If the file is not a valid image, or copying fails.

validate_creds(creds: dict, required_keys: tuple[str, ...], setup_type: SetupType) → None

Validates all required keys are present in the credentials.

Parameters:

• creds (dict) – Credentials to validate

• required_keys (tuple[str, ...]) – Keys required to be present in passed credentials.

• setup_type (SetupType) – The SetupType to validate credentials against.

Raises:

SetupError – If any credentials are missing.

Return type:

None

prompt_installomator() → None

Prompts user to enable or disable InstallomatorClient support.

If enabled, assists in identifying PatchTitle objects with InstallomatorClient support, used during analyze commands.

Return type:

None

async get_token(setup_type: SetupType = SetupType.STANDARD, creds: dict | None = None) → str | AccessToken

Fetches a Token (basic or AccessToken) depending on setup type (Standard or SSO).

Parameters:

• setup_type (SetupType) – SetupType specified dictates which type of Token will be retrieved (basic or bearer).

• creds (dict | None) – If SetupType is “Standard”, the user credentials needed to obtain a basic token.

Raises:

SetupError – If either type of Token could not be obtained.

Returns:

For SetupType.STANDARD, the basic token is returned. For SetupType.SSO, the AccessToken object is returned.

Return type:

str | AccessToken

async create_api_client(basic_token: str, jamf_url: str) → tuple[str, str]

Creates API Role and Client for standard setup types.

Parameters:

• basic_token (str) – The basic token used for authorization in creating API Role and Client

• jamf_url (str) – The Jamf Pro instance URL to create API Role and Clients in.

Raises:

SetupError – If either the API Role or API Client could not be created.

Returns:

The client ID and client secret of the created API Client and Role.

Return type:

tuple[str, str]

async bootstrap_noninteractive(client_id: str, client_secret: str, url: str) → None

Non-interactive setup path for CI/CD environments.

Skips all prompts (setup type, InstallomatorClient, UI configuration). The provided credentials are stored via the configured ConfigManager. When that manager is in in-memory mode (the typical CI/CD setup) the macOS keychain is not touched. An access token is then fetched so subsequent API calls succeed.

Setup completion is marked in memory only, with no plist mutation. The next invocation will need to provide credentials again, which is the desired behavior on ephemeral runners.

Parameters:

• client_id (str) – Jamf Pro API client ID.

• client_secret (str) – Jamf Pro API client secret.

• url (str) – Jamf Pro instance URL.

Raises:

SetupError – If a token cannot be obtained with the provided credentials.

Return type:

None

async start(spinner=None, fresh: bool = False) → None

Run the interactive setup flow end-to-end.

Returns early if setup has already completed unless fresh=True is passed (which re-runs the full flow regardless of previous completion). Prompts for setup type, then walks the full path: credentials → API role + client creation (Standard only) → bearer token fetch → JamfClient save → UI configuration → mark complete.

Options:

• STANDARD prompts for admin username/password, fetches a basic token, creates the API role + client on the Jamf side, and saves the resulting client credentials.

• SSO prompts for an existing API client ID + secret and saves them directly.

See also

For SSO users, reference our SSO Considerations page for assistance creating an API integration.

Note

If a previous attempt failed after the Jamf API role + client were created, a Standard re-run will fail with a 400 because those objects already exist. Either delete them from Jamf and retry, or switch to SSO setup and reuse them.

Parameters:

• spinner (rich.status.Status | _NoOpStatus | None) – The live Rich status (or _NoOpStatus) whose message is updated as setup progresses. Stored on self._spinner so helper methods can update it. Defaults to a no-op.

• fresh (bool) – If True, re-run setup even when already completed.

Raises:

SetupError – If a token cannot be fetched, credentials are missing, or any other setup step fails.

Return type:

None

reset_setup() → bool

Resets setup completion flag, removing the setup_completed key/value from the property list.

This effectively marks Setup completion as False and will re-trigger the setup assistant.

Warning!

The Jamf API will return a 400 response if API Roles/Clients exist already in the Jamf instance specified. It is important to remove the API Role and Client objects before re-running the Setup assistant.

Returns:

True if the Setup section in the property list file was removed.

Return type:

bool

Setup Type

class SetupType(*values)

Defines the method of setup used for configuring Patcher.

• STANDARD: Prompts for Jamf Pro username/password and creates an API client.

• SSO: Prompts for an existing API client ID and secret.

STANDARD = 'standard'

SSO = 'sso'