Metadata-Version: 2.4
Name: abxrcli
Version: 0.15.0
Summary: ArborXR CLI
Author-email: Peter Peterson <peter@arborxr.com>
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: pyyaml
Dynamic: license-file

# ArborXR CLI

This CLI tool provides commands for managing apps and files via the ArborXR API. The tool is organized into command groups: apps and files. Each group has several subcommands to perform specific operations through the command line.

## Prerequisites

Before using the CLI tool, you must perform the following:
* Python 3 installed on your system.
* An API Token for authentication
    * Login to your ArborXR Account
    * Navigate to Settings > Access Tokens
    * Create an API Access Token for your organization
* Setting the API token
    * The environment variable ABXR_API_TOKEN (or the alternative ARBORXR_ACCESS_TOKEN), or
    * The command line option --token.

## Setup

ArborXR CLI is available through PyPI. If you have `pip` installed, you can get the latest version by installing via:
```
pip install abxrcli
```

## Global Options

### The CLI tool accepts the following global options:
`-u, --url`
* Description: API Base URL
* Default: https://api.xrdm.app/api/v2 (or the value of ABXR_API_URL environment variable)

`-t, --token`
* Description: API Token for authentication
* Default: Value of ABXR_API_TOKEN (or ARBORXR_ACCESS_TOKEN)

`-f, --format`
* Description: Data output format
* Choices: json or yaml
* Default: yaml

`-v, --version`
* Description: Show the CLI tool version and exit

`-s, --silent`
* Description: Disable any terminal printing of progress bars for longer operations, like file uploads.

## Command Groups

The CLI tool is divided into multiple groups including apps, app_bundles, files, and devices. Each group has its own set of subcommands.

### Apps Commands

These commands manage app-related operations.

#### Subcommands

##### list
* Usage:
`abxr-cli apps list`
* Description: List all available apps.


##### details
* Usage:
`abxr-cli apps details app_id`
* Positional Argument:
    * `app_id`: The unique identifier of the app.
* Description: Retrieve detailed information about a specific app.


##### versions
* Usage:
`abxr-cli apps versions app_id`
* Positional Argument:
    * `app_id`: The unique identifier of the app.
* Description: List all versions available for a specific app.


##### release_channels
* Usage:
`abxr-cli apps release_channels app_id`
* Positional Argument:
    * `app_id`: The unique identifier of the app.
* Description: List all release channels associated with a specific app.


##### release_channel_details
* Usage:
`abxr-cli apps release_channel_details app_id [--release_channel_id RELEASE_CHANNEL_ID]`
* Positional Argument:
    * `app_id`: The unique identifier of the app.
* Optional Argument:
    * --release_channel_id: The identifier for a specific release channel.
* Description: Get details for a release channel of an app.

##### release_channel_set_version
* Usage:
`abxr-cli apps release_channel_set_version app_id [--release_channel_id RELEASE_CHANNEL_ID] [--version_id VERSION_ID]`
* Positional Argument:
    * `app_id`: The unique identifier of the app.
* Optional Arguments:
    * --release_channel_id: The identifier for the release channel.
    * --version_id: The version identifier to set for the channel.
* Description: Assign a specific version to a release channel.

##### upload
* Usage:
`abxr-cli apps upload app_id filename [--version VERSION] [--notes NOTES] [--release-channel-id ID | --new-release-channel-title TITLE]`
* Positional Arguments:
    * `app_id`: The unique identifier of the app.
	* `filename`: Local path of the APK/ZIP (apk+obb) file to upload.
* Optional Arguments:
	* -v, --version: Version number (note that the Uploaded APK itself can override this value).
	* -n, --notes: Release notes for the new version.
	* --release-channel-id: ID of existing release channel to associate with this version.
	* --new-release-channel-title: Title for a new release channel to create and associate with this version.
* Description: Upload a new version of an app (APK/ZIP only). To upload an app bundle with associated files, use the `app_bundles upload` command. You can optionally associate the upload with a release channel using either --release-channel-id or --new-release-channel-title (mutually exclusive).

##### share
* Usage:
`abxr-cli apps share app_id --release_channel_id RELEASE_CHANNEL_ID --organization_slug ORGANIZATION_SLUG`
* Positional Argument:
	* `app_id`: The unique identifier of the app.
* Required Options:
	* --release_channel_id: The release channel to be shared.
	* --organization_slug: The organization slug with which the app is to be shared.
* Description: Share an app with a specific organization and release channel.

##### revoke
* Usage:
`abxr-cli apps revoke app_id --release_channel_id RELEASE_CHANNEL_ID --organization_slug ORGANIZATION_SLUG`
* Positional Argument:
	* `app_id`: The unique identifier of the app.
* Required Options:
	* --release_channel_id: The release channel from which to revoke sharing.
	* --organization_slug: The organization slug from which the app sharing should be revoked.
* Description: Revoke sharing of an app from a specific organization and release channel.


### App Bundles Commands

App bundles combine an app version with associated files that should be deployed together. These commands manage the creation, upload, and management of app bundles.

**Folder Structure and Device Paths:**
The APK file and bundle folder are provided separately. Files in your bundle folder are automatically mapped to device paths under `/sdcard/`. The folder structure is preserved:
- Files in the root folder → `/sdcard/`
- Files in subfolders → `/sdcard/{subfolder_path}/`

You can optionally specify a custom base path using `--device-path` to map files under a subdirectory of `/sdcard/`.

Example (default mapping):
```
bundle-folder/
  config.json                → /sdcard/config.json
  data/
    user.json                → /sdcard/data/user.json
    cache/
      temp.dat               → /sdcard/data/cache/temp.dat
```

Example (with `--device-path myapp/config`):
```
bundle-folder/
  config.json                → /sdcard/myapp/config/config.json
  data/
    user.json                → /sdcard/myapp/config/data/user.json
```

**Hash-Based Deduplication:**
The CLI automatically detects and reuses existing builds and files based on their content hash (SHA-256 for builds, SHA-512 for files). This means:
- Uploading the same APK multiple times only stores it once
- Files that haven't changed are reused across bundles
- Only new or modified files are uploaded, saving time and bandwidth

#### Subcommands

##### upload
* Usage:
`abxr-cli app_bundles upload <app_id> <apk_path> <bundle_folder> [--version-number VERSION] [-n NOTES] [--device-path PATH] [--release-channel-id ID | --new-release-channel-title TITLE]`
* Positional Arguments:
    * <app_id>: The unique identifier of the app.
    * <apk_path>: Path to APK file.
    * <bundle_folder>: Path to folder containing bundle files.
* Optional Arguments:
    * --version-number: Version number (APK can override this value, only used for new builds).
    * -n, --notes: Release notes for the bundle.
    * --device-path: Optional device path relative to /sdcard for bundle files (e.g., "myapp/config").
    * --release-channel-id: ID of existing release channel to associate with this bundle.
    * --new-release-channel-title: Title for a new release channel to create and associate with this bundle.
* Description: Upload an APK and all bundle files from a folder, then finalize the bundle. Bundle labels are auto-generated by the system. Automatically reuses existing builds and files based on hash matching for faster uploads. You can optionally associate the bundle with a release channel using either --release-channel-id or --new-release-channel-title (mutually exclusive).

##### list
* Usage:
`abxr-cli app_bundles list <app_id> [--status STATUS]`
* Positional Argument:
    * <app_id>: The unique identifier of the app.
* Optional Arguments:
    * --status: Filter by status (pending, processing, failed, available).
* Description: List all app bundles for a specific app.

##### details
* Usage:
`abxr-cli app_bundles details <app_bundle_id>`
* Positional Argument:
    * <app_bundle_id>: The unique identifier of the app bundle.
* Description: Get detailed information about a specific app bundle.

##### resume
* Usage:
`abxr-cli app_bundles resume <bundle_id> <apk_path> <folder_path> [--device-path PATH]`
* Positional Arguments:
    * <bundle_id>: The unique identifier of the bundle to resume.
    * <apk_path>: Path to APK file (must match original).
    * <folder_path>: Path to folder containing the original bundle files.
* Optional Arguments:
    * --device-path: Device path relative to /sdcard (must match original upload if used).
* Description: Resume a failed or interrupted bundle upload. Validates that the APK, folder structure, and device path match the original bundle, then uploads any missing files and finalizes the bundle.

##### create_from_build
* Usage:
`abxr-cli app_bundles create_from_build <build_id> <bundle_folder> <app_id> [--device-path PATH] [--release-channel-id ID | --new-release-channel-title TITLE] [-s]`
* Positional Arguments:
    * <build_id>: The unique identifier of an existing app build/version.
    * <bundle_folder>: Path to folder containing bundle files.
    * <app_id>: The unique identifier of the app (needed for file deduplication).
* Optional Arguments:
    * --device-path: Optional device path relative to /sdcard for bundle files.
    * --release-channel-id: ID of existing release channel to associate with this bundle.
    * --new-release-channel-title: Title for a new release channel to create and associate with this bundle.
    * -s, --silent: Suppress progress bars and other output.
* Description: Create an app bundle using an existing build without re-uploading the APK. This is useful when you want to create multiple bundles with different file sets from the same build, or when you already have a build and just need to add files to it. Automatically reuses existing files based on hash matching. You can optionally associate the bundle with a release channel using either --release-channel-id or --new-release-channel-title (mutually exclusive).

##### update_label
* Usage:
`abxr-cli app_bundles update_label <app_bundle_id> {--label LABEL | --clear}`
* Positional Argument:
    * <app_bundle_id>: The unique identifier of the app bundle.
* Required Options (mutually exclusive):
    * --label: New label for the bundle (max 60 characters).
    * --clear: Remove the label from the bundle.
* Description: Update or remove an app bundle's label. Labels help identify different bundles for the same app. Use --label to set a new label or --clear to remove the existing label.


### Files Commands

These commands are used for file-related operations.

#### Subcommands

##### list
* Usage:
`abxr-cli files list`
* Description: List all files available.


##### details
* Usage:
`abxr-cli files details file_id`
* Positional Argument:
	* `file_id`: The unique identifier of the file.
* Description: Get detailed information for a specific file.

### Devices Commands

These commands are used for device-related operations

#### Subcommands

##### list
* Usage:
`abxr-cli devices list`
* Description: List all devices


##### details
* Usage:
`abxr-cli devices details device_id`
* Positional Argument:
    * `device_id`: The unique identifier for the device.
* Description: Get detailed information about a device.


##### launch
* Usage:
`abxr-cli devices launch device_id --app_id=app_id`
* Positional Argument:
    * `device_id`: The unique identifier for the device.
* Required Options:
    * --app_id: The unique identifier of the application you want to launch
* Description: Launch an application immediately on a device.


##### reboot
* Usage:
`abxr-cli devices reboot device_id`
* Positional Argument:
    * `device_id`: The unique identifier for the device.
* Description: Reboot a device immediately.



## CLI Usage Examples

These examples assume you have set the `ABXR_API_TOKEN` in your environment. 

### Listing all apps

`abxr-cli apps list`

### Getting details of a specific app

`abxr-cli apps details 123e4567-e89b-12d3-a456-426614174000`

### Listing versions of an app

`abxr-cli apps versions 123e4567-e89b-12d3-a456-426614174000`

### Uploading a new version of an app

Basic upload:

`abxr-cli apps upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk --version 1.2.3 --notes "Bug fixes and performance improvements"`

Upload to an existing release channel:

`abxr-cli apps upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk --release-channel-id 9451f229-1833-4327-a708-e8a2a5c8d377`

Upload and create a new release channel:

`abxr-cli apps upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk --new-release-channel-title "Beta Channel"`

### Sharing an app with an organization

`abxr-cli apps share 123e4567-e89b-12d3-a456-426614174000 --release_channel_id 6789 --organization_slug myorg`

### Listing all files

`abxr-cli files list`

### Uploading an app bundle with files

Upload an APK and associated files from a folder:

`abxr-cli app_bundles upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder`

With version number and release notes:

`abxr-cli app_bundles upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder --version-number "1.0.0" --notes "Initial production release"`

With a custom device path (files will be placed under /sdcard/myapp/config/):

`abxr-cli app_bundles upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder --device-path myapp/config`

Upload to an existing release channel:

`abxr-cli app_bundles upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder --release-channel-id 9451f229-1833-4327-a708-e8a2a5c8d377`

Upload and create a new release channel:

`abxr-cli app_bundles upload 123e4567-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder --new-release-channel-title "Production Channel"`

### Listing app bundles

List all bundles for an app:

`abxr-cli app_bundles list 123e4567-e89b-12d3-a456-426614174000`

List only pending bundles:

`abxr-cli app_bundles list 123e4567-e89b-12d3-a456-426614174000 --status pending`

### Getting app bundle details

`abxr-cli app_bundles details 789e1234-e89b-12d3-a456-426614174000`

### Resuming a failed bundle upload

If an upload fails or is interrupted, you can resume it:

`abxr-cli app_bundles resume 789e1234-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder`

If the original upload used a custom device path, you must provide it when resuming:

`abxr-cli app_bundles resume 789e1234-e89b-12d3-a456-426614174000 /path/to/app.apk /path/to/bundle-folder --device-path myapp/config`

### Creating a bundle from an existing build

If you already have an uploaded build and want to create a bundle with files without re-uploading the APK:

`abxr-cli app_bundles create_from_build abc12345-e89b-12d3-a456-426614174000 /path/to/bundle-folder 123e4567-e89b-12d3-a456-426614174000`

With a custom device path:

`abxr-cli app_bundles create_from_build abc12345-e89b-12d3-a456-426614174000 /path/to/bundle-folder 123e4567-e89b-12d3-a456-426614174000 --device-path myapp/data`

With a release channel:

`abxr-cli app_bundles create_from_build abc12345-e89b-12d3-a456-426614174000 /path/to/bundle-folder 123e4567-e89b-12d3-a456-426614174000 --release-channel-id 9451f229-1833-4327-a708-e8a2a5c8d377`

Create multiple bundles from the same build with different file sets:

```bash
# First bundle with config files
abxr-cli app_bundles create_from_build abc12345-e89b-12d3-a456-426614174000 /path/to/config-files 123e4567-e89b-12d3-a456-426614174000

# Second bundle with media files
abxr-cli app_bundles create_from_build abc12345-e89b-12d3-a456-426614174000 /path/to/media-files 123e4567-e89b-12d3-a456-426614174000
```

### Updating an app bundle's label

Set a custom label for a bundle:

`abxr-cli app_bundles update_label 789e1234-e89b-12d3-a456-426614174000 --label "Production Release v2.0"`

Remove a label from a bundle:

`abxr-cli app_bundles update_label 789e1234-e89b-12d3-a456-426614174000 --clear`


## Error Handling

* If the API token is missing (not provided via --token or environment variables), the tool will print:

`API Token is required. Please set the ABXR_API_TOKEN environment variable or use the --token command line param`
