Command Line Interface for launchpy

This document provides an overview of the command line interface (CLI) for launchpy, a tool designed to facilitate the launching of applications and services. The CLI allows users to interact with launchpy directly from the terminal, providing a convenient way to manage and execute tasks.

Table of Contents:

Command Line Interface for launchpy

Prequisites

Before using the launchpy CLI, ensure that you have the following prerequisites:

Python 3.10 or higher installed on your system.
Access to a terminal or command prompt.
An active internet connection to install launchpy and its dependencies.
An Adobe Developer Project that is connected to your Adobe Launch / Adobe Experience Platform Data Collection Tags. This would provide the information required (client_id, secret, org_id, scopes) to use the CLI to launch your applications and services.

Installation

You would need to have Python installed on your system to use launchpy. The recommended version is Python 3.10 or higher. You can check your Python version by running:

python --version

In order to use the CLI, you would need to have at least the version 0.4.7 of launchpy. To install launchpy, you can use pip:

pip install launchpy

to upgrade to the latest version, you can run:

pip install --upgrade launchpy

Usage

Once installed, you can access the launchpy CLI by running the following command in your terminal:

python -m launchpy.cli

launchpy CLI provides various commands nested in different layer:

Main Layer : This is the top layer of the CLI where you can access the main functionalities such as creating a config file and setting up the configuration for API connection. It can be recognized by the (Cmd) or launchpy> (once config has been ran) prompt.
Property Layer: This layer allows you to access information about a specific Launch property and perform actions related to that property. It can be recognized by the property_name> prompt, where property_name is replaced by the name of your property. You can directly access this layer by providing the property name in the config command in the main layer.
Synchronizer Layer: This layer is focused on synchronizing Launch properties. It provides commands to check for updates and synchronize your property. It can be recognized by the synchronizer:base_property> prompt, where base_property will be replaced by the name of your base property.

All layers contains the following common commands:

help : Display the help message with a list of available commands and their descriptions.
exit : Exit the CLI.

Instantiation

Once you have started the CLI, you can either create a config file if needed, or load the config file in the config method. The config method also take individual parameters as arguments, which would override the values in the config file.

create_config_file

Create a config file to store your credentials and other necessary information for using launchpy. This is a one-time setup step that allows you to save your configuration for future use.
Arguments: -fn, --file_name: The name of the config file to be created. If not provided, it defaults to launchpy_config.json. -m, --multi_org: Flag. If present, generate a config file template for multiple organizations (a JSON list, each entry with its own org_name) instead of the default single-organization template (a JSON object).

You can create a config file by running the following command:

python -m launchpy.cli
(Cmd) create_config_file

If you need to connect to several Adobe Experience Platform organizations from the same CLI session, generate a multi-org template instead:

python -m launchpy.cli
(Cmd) create_config_file --multi_org

This produces a JSON list of config blocks (instead of a single JSON object), where each block requires an org_name key used to reference that organization, for example:

[
    {
        "org_id": "<orgID>",
        "client_id": "<client_id>",
        "secret": "<YourSecret>",
        "scopes": "<scopes>",
        "org_name": "<org_name>"
    }
]

You can duplicate that block for each organization you want to connect to, giving each a unique org_name. See the config and change_org commands below for how to use this file.

config

Setup the API connection to use the full capacity of the CLI. Arguments -cid,--client_id: The client ID for your Adobe Developer Project. This is a required parameter. -s,--secret: The secret key for your Adobe Developer Project. This is a required parameter. -o,--org_id: The organization ID associated with your Adobe Developer Project. This is a required parameter. -sc,--scopes: The scopes that define the permissions for your API connection. This is a required parameter. -cf,--config_file: The path to the config file that contains your credentials and other necessary information. -p,--property : The property name to be used and directly instantiated the property layer. This is an optional parameter. -on,--org_name: The organization name to use when your --config_file is a multi-org config file (see create_config_file). This is an optional parameter, it defaults to the first organization found in the file (or default when using individual parameters).

Example via parameters:

python -m launchpy.cli
(Cmd) config --client_id <your_client_id> --secret <your_secret> --org_id <your_org_id> --scopes <your_scopes>

Example via config file:

python -m launchpy.cli
(Cmd) config --config_file <path_to_your_config_file>

Example with direct access to property layer:

python -m launchpy.cli
(Cmd) config --config_file <path_to_your_config_file> --property <your_property_name>

TIP When you are instantiating the CLI, you can directly pass the credentials information:

python -m launchpy.cli --client_id <your_client_id> --secret <your_secret> --org_id <your_org_id> --scopes <your_scopes>

python -m launchpy.cli --config_file <path_to_your_config_file>

It also supports direct access to the property layer by providing the property name in the parameters:

python -m launchpy.cli --config_file <path_to_your_config_file> --property <your_property_name>

Example with a multi-org config file, connecting directly to the client_a organization:

python -m launchpy.cli
(Cmd) config --config_file <path_to_your_multi_org_config_file> --org_name client_a
launchpy:client_a>

When in a non-multi-org environment, the prompt of the CLI will be launchpy>, and when in a multi-org environment, the prompt will be launchpy:<org_name>, where <org_name> is the name of the organization you are currently connected to.
By default, the first organization found in the multi-org config file will be used if no --org_name is provided. You can switch between organizations using the change_org command.

change_org

Switch the current CLI session to another organization that has already been loaded from a multi-org config file (via config or --config_file at startup). This avoids re-running config when you need to move between organizations.
Arguments: org_name: The name of the organization to switch to, matching one of the org_name values in your multi-org config file. This is a required parameter.

python -m launchpy.cli
(Cmd) config --config_file <path_to_your_multi_org_config_file>
launchpy:client_a> change_org client_b
launchpy:client_b>

get_properties

Retrieve a list of properties associated with your Adobe Developer Project. This command allows you to view the properties that you have access to and can manage using launchpy.
Arguments: -n,--name: The name of the property to filter the results (partial match, non-case sensitive). This is an optional parameter. -s,--save: Boolean. Save properties to a CSV file. Default False. Possible values: True, False

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> get_properties -n <property_name> -s True

create_property

Create a new property in your Adobe Launch account. This command allows you to set up a new property that you can manage and synchronize using launchpy.
Arguments: name : The name of the new property to be created. This is a required parameter. -d,--description: The description of the new property. This is an optional parameter. -p,--platform: The platform for the new property. Default 'web', possible values: 'web', 'mobile'. This is an optional parameter.

Example:

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> create_property "New Property" --description "This is a new property"

delete_property

Delete an existing property from your Adobe Launch account. This command allows you to remove a property that you no longer need or want to manage using launchpy.
Arguments: name: The name of the property to be deleted. This is a required parameter.

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> delete_property "Property Name"

extract_property

This method allows you to extract the details of a specific property and save them to a folder.
By default, the folder name would be the name of the property, and it will contain sub folders for each rule.
Arguments: name: The name of the property to extract. This is a required parameter. -p, --published_version: Boolean. Extract only the latest published version of the components instead of the current (development) version. Default False. Possible values: True, False -f, --folder: The folder to extract the property into. This is an optional parameter, if not provided, it defaults to a folder named after the property in the current working directory.

This can be useful for searching code or for backup purposes.

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> extract_property "Property Name"

Example extracting the latest published version into a specific folder:

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> extract_property "Property Name" --published_version True --folder "./exports/property_name"

load_property

This method load the property layer for a specific property, allowing you to access and manage that property directly. Arguments: name: The name of the property to load. This is a required parameter.

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> load_property "Property Name"
property_name>

get_extensions

List all available extensions in the connected Adobe Launch organization. Arguments: -s, --save: Boolean. Save extensions to a JSON file. Default False. Possible values: True, False

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> get_extensions -s True

load_synchronizer

Load the synchronizer layer, allowing you to manage and synchronize properties with extensions, rules and data elements.
Arguments: base_name: Name of the Launch Property to use as base. -t, --targets: list of target property names for synchronization. This is a required parameter. -dy, --dynamic_component: Name of the Data Element that would contain dynamic component rules. This is an optional parameter, if not provided, it would not use dynamic component rules.

python -m launchpy.cli -cf <path_to_your_config_file>
launchpy> load_synchronizer "Base Property Name" -t "Target Property 1" "Target Property 2" -dy "Dynamic Component Data Element Name"
synchronizer:Base_Property_Name>

Synchronizing across organizations
The synchronizer also supports a base property and/or target properties that live in a different Adobe organization than the one currently active in the CLI. This is useful when you manage several IMS orgs and want to push the same rules, data elements and extensions from a single base property to properties in other orgs.

To reference a property in another organization, append @<org_name> to its name, where <org_name> matches an org_name entry from a multi-org config file (see create_config_file). Any property name without @<org_name> is resolved against the organization that is currently active in the session (the one last set via config or change_org).

First, load a multi-org config file so every organization you want to reference is available in the session:

python -m launchpy.cli -cf <path_to_your_multi_org_config_file> --org_name client_a
launchpy:client_a>

Then load the synchronizer using @org_name on the base and/or the targets:

launchpy:client_a> load_synchronizer "Base Property Name@client_a" -t "Target Property 1@client_b" "Target Property 2@client_c"
synchronizer:Base_Property_Name>

Organizations can be mixed freely; targets that omit @org_name resolve to the currently active organization (client_a below):

launchpy:client_a> load_synchronizer "Base Property Name" -t "Target Property 1" "Target Property 2@client_b"
synchronizer:Base_Property_Name>

Note: if a private extension used by the base property is named differently in a target organization, the CLI cannot map the two names for you — this requires passing a mapping_extensions dictionary ({"target-extension-name": "base-extension-name"}) to launchpy.Synchronizer directly through the Python API, usually done via a Notebook, since that option is not exposed as a CLI flag.

Property Layer Commands

Once you have instantiated the property layer for a specific property, you can access various commands to manage that property. These commands allow you to perform actions such as viewing and editing rules, data elements, and other configurations related to that property.

get_extensions

Get all extensions in the property and list them.
Arguments: -s, --save: Flag. Save extensions to a CSV file. Default False.

property_name> get_extensions -s

get_extension

Get details of a specific extension in the property.
Arguments: name: The name of the extension to retrieve details for. This is a required parameter. -s, --save: Flag. Save the extension details to a JSON file. Default False.

property_name> get_extension "Extension Name" -s

get_rules

Get all rules in the property and list them.
Arguments: -n, --name: The name of the rule to filter the results (partial match, non-case sensitive). This is an optional parameter. -s, --save: Flag. Save rules to a CSV file. Default False.

property_name> get_rules -n "Rule Name" -s

get_rule

Get details of a specific rule in the property.
Arguments: name: The name of the rule to retrieve details for. This is a required parameter. -s, --save: Flag. Save the rule details to a JSON file. Default False.

property_name> get_rule "Rule Name" -s

get_rules_components

Get all rule components, and save them to a CSV file if specified. Intended to be used for all components, but can be filtering.
Arguments: -s, --save: Flag. Save rules components to a CSV file. Default False. -rn, --rule_name: (Partial) Name of the rule to get components for. This is an optional parameter. -rid, --rule_id: ID of the rule to get components for. This is an optional parameter, if both rule_name and rule_id are provided, it will use rule_id.

property_name> get_rules_components -s

get_rule_components

Get all components for a specific rule by name or ID. Way more effective than the other methods and provide more details.
Arguments: -s, --save: Flag. Save the rule components to a JSON file. Default False. -rn, --rule_name: (Partial) Name of the rule to get components for. This is an optional parameter. -rid, --rule_id: ID of the rule to get components for. This is an optional parameter, if both rule_name and rule_id are provided, it will use rule_id.

property_name> get_rule_components -rn "Rule Name" -s

get_data_elements

Get all data elements in the property and list them.
Arguments: -n, --name: The name of the data element to filter the results (partial match, non-case sensitive). This is an optional parameter. -s, --save: Boolean. Save data elements to a CSV file. Default False. Possible values: True, False

property_name> get_data_elements -n "Data Element Name" -s True

get_data_element

Get details of a specific data element in the property.
Arguments: name: The name of the data element to retrieve details for. This is a required parameter. -s, --save: Flag. Save the data element details to a JSON file. Default False.

property_name> get_data_element "Data Element Name" -s

get_latest_published_version

Get the latest published version of a specific component in the property.
Arguments: -n, --name: The name of the component to get the latest published version for. This is a required parameter. -t, --type: The type of the component (e.g. 'rule', 'data_element', 'extension') to get the latest published version for. This is a required parameter. -s, --save: Flag. Save the latest published version details to a JSON file. Default False.

property_name> get_latest_published_version -n "Component Name" -t "rule" -s

get_libraries

Get all libraries in the property and list them.
Arguments: -s, --save: Flag. Save libraries to a CSV file. Default False. -st, --state: Filter by library state. Possible values: 'development' (default), 'submitted', 'approved', 'rejected', 'published'. This is an optional parameter.

property_name> get_libraries -s -st "development"

delete_library

Delete a library from the property.
Arguments: name: The name of the library to delete. This is a required parameter.

property_name> delete_library "Library Name"

delete_library_components

Delete components from a library.
Arguments: name: The name of the library to delete components from. This is a required parameter.

property_name> delete_library_components "Library Name"

create_env

Create a new environment based on Adobe host in the property.
Arguments: name: The name of the environment to create. This is a required parameter.

property_name> create_env "Environment Name"

Synchronizer Layer Commands

Once you have loaded the synchronizer layer for a specific base property, you can access commands to manage and synchronize that property with target properties. These commands allow you to perform actions such as checking for updates, synchronizing properties, and managing dynamic component rules.

check_component

Check if a specific component is in sync between the base property and target properties.
Arguments: -n, --name: The name of the component to check for synchronization. This is a required parameter. -id, --id: ID of the component to check (overrides name if both provided) -p, --published : Flag. Check the synchronization based on the latest published version of the component. Default False.

synchronizer:Base_Property_Name> check_component -n "Component Name" -p

sync

Synchronize a specific component between the base property and target properties.
Arguments: -n, --name: The name of the component to synchronize. This is a required parameter. -id, --id: ID of the component to synchronize (overrides name if both provided) -p, --published : Flag. Synchronize the latest published version of the component. Default False. -c, --create : Flag. Create the component if it does not exist. Default False. -v, --verbose : Flag. Print detailed information about the sync process. Default False.

synchronizer:Base_Property_Name> sync -n "Component Name" -p -c

sync_rules

Synchronize all rules between the base property and target properties in a single call, instead of syncing them one by one with sync.
Arguments: -r, --regex: Regex pattern to filter rules by name (partial match, non-case sensitive). This is an optional parameter, if not provided, all rules are synced. -c, --create : Flag. Create rules that do not exist in the destination property. Default False. -p, --published : Flag. Sync the latest published version of the rules. Default False.

synchronizer:Base_Property_Name> sync_rules -r "Rule Name" -c

sync_data_elements

Synchronize all data elements between the base property and target properties in a single call, instead of syncing them one by one with sync.
Arguments: -r, --regex: Regex pattern to filter data elements by name (partial match, non-case sensitive). This is an optional parameter, if not provided, all data elements are synced. -c, --create : Flag. Create data elements that do not exist in the destination property. Default False. -p, --published : Flag. Sync the latest published version of the data elements. Default False.

synchronizer:Base_Property_Name> sync_data_elements -r "Data Element Name" -c

sync_extensions

Synchronize all extensions between the base property and target properties in a single call, instead of syncing them one by one with sync.
Arguments: -r, --regex: Regex pattern to filter extensions by name (partial match, non-case sensitive). This is an optional parameter, if not provided, all extensions are synced. -c, --create : Flag. Create extensions that do not exist in the destination property. Default False. -v, --verbose : Flag. Print detailed information about the sync process. Default False.

synchronizer:Base_Property_Name> sync_extensions -r "Extension Name" -c

rename_component

Rename a component in the destination property. Arguments: current_name : The current name of the component to rename. This is a required parameter. new_name: The new name for the component. This is a required parameter.

synchronizer:Base_Property_Name> rename_component "Current Component Name" "New Component Name"

get_targets

Get the target properties for synchronization. This command allows you to view the properties that are set as targets for synchronization with the base property.

synchronizer:Base_Property_Name> get_targets

upgrade_extension

Upgrade an extension in the destination property to the latest version available in the base property. Arguments: name: The name of the extension to upgrade. This is a required parameter. -p, --platform: The platform of the extension to upgrade (e.g. 'web', 'app'). This is an optional parameter. Default web.

synchronizer:Base_Property_Name> upgrade_extension "Extension Name"

get_base_rules

This command allows you to view the rules that are availble in the base property for synchronization with the target properties.
Arguments: -n, --name: The name of the rule to filter the results (partial match, non-case sensitive). This is an optional parameter.

synchronizer:Base_Property_Name> get_base_rules -n "Rule Name"

get_base_data_elements

This command allows you to view the data elements that are availble in the base property for synchronization with the target properties.
Arguments: -n, --name: The name of the data element to filter the results (partial match, non-case sensitive). This is an optional parameter.

synchronizer:Base_Property_Name> get_base_data_elements -n "Data Element Name"

get_base_extensions

This command allows you to view the extensions that are availble in the base property for synchronization with the target properties.
Arguments: -n, --name: The name of the extension to filter the results (partial match, non-case sensitive). This is an optional parameter.

synchronizer:Base_Property_Name> get_base_extensions -n "Extension Name"

get_base_libraries

This command allows you to view the libraries that are availble in the base property for synchronization with the target properties.
Arguments: -s, --state: Filter by library state. Possible values: 'published'(default),'development' , 'submitted', 'approved', 'rejected'. This is an optional parameter. -n, --name: Filter base libraries by name (partial match, non-case sensitive). This is an optional parameter. -d, --days: Filter libraries that have been updated in the last X days. This is an optional parameter.

synchronizer:Base_Property_Name> get_base_libraries -s "published" -n "Library Name" -d 30

get_base_library

This command allows you to view the details of a specific library that is availble in the base property for synchronization with the target properties.
It returns the rule, data elements and extensions that are part of the library, as well as the details of the library itself.
Arguments: -n, --name: The name of the library to get details for. This is a required parameter. -id, --id: The ID of the library to get details for (overrides name if both provided). This is an optional parameter.

synchronizer:Base_Property_Name> get_base_library -n "Library Name"

sync_from_library

This command allows you to synchronize a library from the base property to the target properties.
IMPORTANT:By default it will use the published version of the elements that are part of the library.

-n, --name: Name of the library to sync from. This is a required parameter.
-id, --id: ID of the library to sync from (overrides name if both provided). This is an optional parameter.
-c, --create: Boolean. Create the component if it does not exist. Default False. Possible values: True, False
-ll, --library_linked: Boolean. Whether to use library linked components or not. If set to True, the sync will be done using the library linked components. If set to False, the sync will be done using the component IDs in the library. Default True. Possible values: True, False
-p, --published: Boolean. Sync the latest published version of the component instead of the current version. Default False. Possible values: True, False
-dr, --dry_run: Boolean. If set to True, will only check the sync status of the components without actually syncing them. Default False. Possible values: True, False

synchronizer:Base_Property_Name> sync_from_library -id "LibraryId" -ll False -p True -dr True

Behaviors for sync_from_library

By default, the method will sync the components present in the library as they are in the library. If the published is set to True, it will try to sync the version that has been published in the base property to the targets.
If the library_linked is set to False and the published is set to False (default), it will try to sync the latest version of the components present in the base property library to the targets.\

synchronizer:Base_Property_Name> sync_from_library -n "Library Name"

create_libraries

This command allows you to create a library in the destination properties with the elements you have sync.
Arguments: name: Name for the new library to be created in the destination properties. This is a required parameter. -env, --environment: String. If set to True, it will try to find a free environment and assign it to the library. If none is available, it will not assign any environment to the library. If the name of the environment is provided, it will try to assign it to that library. If the environment is already used in a Library, it will remove that association and assign it to the new library. Default False. Possible values: True, False or a string which is the (partial) name of the environment you want to assign to the library.

synchronizer:Base_Property_Name> create_library "Library Name" -env True

synchronizer:Base_Property_Name> create_library "Library Name" -env "Environment Name

FilesExpand file tree

cli.md

Latest commit

History

cli.md

File metadata and controls

Command Line Interface for launchpy

Prequisites

Installation

Usage

Instantiation

create_config_file

config

change_org

get_properties

create_property

delete_property

extract_property

load_property

get_extensions

load_synchronizer

Property Layer Commands

get_extensions

get_extension

get_rules

get_rule

get_rules_components

get_rule_components

get_data_elements

get_data_element

get_latest_published_version

get_libraries

delete_library

delete_library_components

create_env

Synchronizer Layer Commands

check_component

sync

sync_rules

sync_data_elements

sync_extensions

rename_component

get_targets

upgrade_extension

get_base_rules

get_base_data_elements

get_base_extensions

get_base_libraries

get_base_library

sync_from_library

Behaviors for sync_from_library

create_libraries