Launchable CLI

Common errors

• Error: 'launchable' command not found. or OSError: [Errno 2] No such file or directory: 'launchable'

  cause The 'launchable' executable is not installed or not available in the system's PATH environment variable.
  fix Ensure the library is installed with `pip install launchable` and that your `~/.local/bin` (or equivalent) is in your PATH, or specify the full path to the `launchable` executable.

• Error: API key is not set. Please set LAUNCHABLE_TOKEN environment variable.

  cause The `LAUNCHABLE_TOKEN` environment variable, required for authentication with the Launchable API, has not been set or is empty.
  fix Set the `LAUNCHABLE_TOKEN` environment variable with your Launchable API key. For example, `export LAUNCHABLE_TOKEN=your_api_key` in a shell, or configure it in your CI/CD system's secrets.

• ModuleNotFoundError: No module named 'launchable.client'

  cause Attempting to `import` a non-existent internal module or assuming a direct Python SDK interface that is not publicly exposed for general use. The `launchable` package is primarily a CLI wrapper, not a traditional Python SDK with exposed high-level programmatic APIs.
  fix Interact with Launchable using the `launchable` command-line tool via `subprocess` calls in Python scripts, rather than attempting direct Python imports of non-public modules.

Warnings

• breaking Major version updates (e.g., from `1.x` to `2.x`) are explicitly stated to introduce drastic changes that break backward compatibility. Pin your dependency to `launchable~=1.0` for stability within the 1.x release line.
  Fix: Use `pip install launchable~=1.0` to constrain installations to the current major version. Review changelogs for migration guides before upgrading major versions.
• gotcha The Launchable CLI requires a Java Runtime Environment (JRE) version 8 or newer to be installed and accessible in the system's PATH, even though the CLI itself is a Python package. This is a common oversight for Python-only environments.
  Fix: Install Java 8 (or a newer compatible version) and ensure its `bin` directory is included in your system's PATH environment variable.
• gotcha Authentication to the Launchable platform primarily relies on the `LAUNCHABLE_TOKEN` environment variable. If this is not set or is incorrect, CLI commands will fail with authentication errors. For open-source projects, tokenless authentication via GitHub OIDC requires specific GitHub Actions YAML configuration.
  Fix: Set the `LAUNCHABLE_TOKEN` environment variable with your API key. For CI/CD, use secret management features of your CI system. For open-source projects, refer to the documentation on 'tokenless authentication'.

Install

• pip install launchable Install latest version
• pip install --user --upgrade launchable~=1.0 Install specific major version

Imports

• launchable

  import subprocess
  subprocess.run(['launchable', '--version'])

  The 'launchable' library is primarily a command-line interface. Direct programmatic interaction for core functionality is typically achieved by invoking the 'launchable' CLI tool via Python's 'subprocess' module, rather than importing specific classes or functions directly from the 'launchable' package itself.

Quickstart

This quickstart demonstrates how to verify your Launchable CLI installation and authentication using Python's `subprocess` module, which is the recommended way for programmatic interaction with the CLI. It assumes the `LAUNCHABLE_TOKEN` environment variable is set for authentication.

import os
import subprocess

# Replace with your actual Launchable API key or retrieve from environment
# For CI/CD, this is typically set as an environment variable (e.g., LAUNCHABLE_TOKEN)
api_key = os.environ.get('LAUNCHABLE_TOKEN', 'YOUR_LAUNCHABLE_API_KEY')

if not api_key or api_key == 'YOUR_LAUNCHABLE_API_KEY':
    print("Warning: LAUNCHABLE_TOKEN environment variable not set. Using placeholder.")
    print("Please set LAUNCHABLE_TOKEN for actual usage.")
    # For demonstration, we'll proceed, but real usage requires a valid token

os.environ['LAUNCHABLE_TOKEN'] = api_key

try:
    print("Verifying Launchable CLI configuration...")
    result = subprocess.run(['launchable', 'verify'], capture_output=True, text=True, check=True)
    print("Launchable CLI verification successful:")
    print(result.stdout)
except subprocess.CalledProcessError as e:
    print(f"Error verifying Launchable CLI: {e.stderr}")
    print("Please ensure LAUNCHABLE_TOKEN is set correctly and Java 8+ is installed.")
except FileNotFoundError:
    print("Error: 'launchable' command not found.")
    print("Please ensure the Launchable CLI is installed and in your system's PATH.")