ICAv2 CLI Plugins

I'm sorry I couldn't think of a superhero pun for this repository

This plugin extends the Illumina Connected Analytics v2 (ICAv2) CLI with higher-level operations for bundle management, project data, pipeline deployment, analysis inspection, and multi-tenant configuration.

Much of this is inspired from the ica-ica-lazy repo.
Autocompletion features are courtesy of the app-spec project.

Please refer to the wiki page for installation and usage.

What's New — Profile-Based Configuration

The CLI now supports AWS CLI-style named profiles stored in ~/.icav2-cli-plugins/config. This replaces the previous shell-function-based tenant/project context management and enables:

• Standalone operation — no shell function sourcing required
• Multi-tenant profiles — switch tenants via ICAV2_PROFILE env var or --profile flag
• Script-friendly — works in subshells, CI/CD pipelines, and non-interactive contexts
• Token caching — per-profile token cache with automatic refresh
• Bundled binary — local _icav2 binary removes external dependency on command icav2
• Fast startup — lazy imports keep icav2 help and icav2 version under 500ms

Quick Start

# Install (downloads icav2 binary + sets up Python env)
bash install.sh

# Configure your first profile
icav2 configure set

# Or configure a named profile
icav2 configure set production

# List configured profiles
icav2 configure list

# Use a specific profile
export ICAV2_PROFILE=production
icav2 projectdata ls /

# Or use the --profile flag
icav2 --profile production projectdata ls /

Config File Format

# ~/.icav2-cli-plugins/config

[default]
server_url = ica.illumina.com
x_api_key = <your-api-key>
project_name = my-project

[profile production]
server_url = ica.illumina.com
x_api_key = <prod-api-key>
project_id = <project-uuid>
output_format = json

Profile Resolution Precedence

Priority	Source
1 (highest)	Environment variables (ICAV2_ACCESS_TOKEN, ICAV2_PROJECT_ID, ICAV2_BASE_URL)
2	--profile CLI flag
3	ICAV2_PROFILE env var
4	ICAV2_TENANT_NAME env var (backward compatibility)
5 (lowest)	[default] profile in config file

Backward Compatibility

Existing environment variables continue to work:

• ICAV2_ACCESS_TOKEN — overrides profile token
• ICAV2_PROJECT_ID — overrides profile project
• ICAV2_BASE_URL — overrides profile server URL
• ICAV2_TENANT_NAME — treated as profile name when ICAV2_PROFILE is unset

The legacy tenants/ directory and shell functions are preserved. Existing workflows using icav2 tenants init / icav2 tenants enter still function.

---

Features

icav2 configure (NEW)

Profile management commands for the new configuration system.

icav2 configure set

Interactively configure a profile (prompts for server URL, API key, project name)

icav2 configure set              # Configure the default profile
icav2 configure set production   # Configure a named profile

icav2 configure list

Display all configured profiles

icav2 configure list

icav2 bundles extensions

Support for generating and deploying bundles.

icav2 bundles init

Initialise a bundle

See more in icav2 bundles init

icav2 bundles get

Get a bundle

See more in icav2_bundles_get

icav2 bundles list

List bundles

See more in icav2_bundles_list

icav2 bundles add-data

Add data to a bundle

See more in icav2_bundles_add_data

icav2 bundles add-pipeline

Add pipeline to a bundle

See more in icav2_bundles_add_pipeline

icav2 bundles release

Release a bundle

See more in icav2_bundles_release

icav2 bundles add-bundle-to-project

Add a released bundle to a project

See more in icav2_bundles_add_to_project

icav2 context handling extensions

icav2 tenants init

Register a tenant with the plugins repository (legacy — consider using icav2 configure set instead)

See more in icav2_context_handling

icav2 tenants list

List available tenants that have been initialised with 'icav2 tenants init'

See more in icav2_context_handling

icav2 tenants enter

Enter a tenant that has been initialised with 'icav2 tenants init'

See more in icav2_context_handling

• Autocompletion ✅

icav2 tenants set-default-project

Set a default project to enter for a given tenant

See more in icav2_context_handling

icav2 tenants set-default-tenant

Set a registered tenant to be the default tenant

See more in icav2_context_handling

icav2 projects enter

Inspired by ica-context-switcher Enter a project in a terminal without affecting default project or other open terminals

• Autocompletion ✅

See more in icav2_context_handling

icav2 projectdata extensions

icav2 projectdata ls

Inspired by gds-ls
List all files and folders in directory

• Autocompletion: ✅

See more in project data wiki

icav2 projectdata view

Inspired by gds-view
View a file in stdout

• Autocompletion: ✅

See more in project data wiki

icav2 projectdata find

Inspired by gds-find
Mimics the gnutls find command with --maxdepth, --mindepth, --type and --name parameters available

• Autocompletion ✅

See more in project data wiki

icav2 projectdata s3-sync-download

Inspired by gds-sync-download
Sync files from icav2 to local project with an aws s3 sync command

• Autocompletion ✅

See more in project data wiki

icav2 projectdata s3-sync-upload

Inspired by gds-sync-upload
Sync files from local to icav2 with an aws s3 sync command

• Autocompletion ✅

See more in project data wiki

icav2 projectdata create-download-script

Inspired by gds-create-download-script
Create a download script with a list of encoded presigned urls for a given directory.

• Autocompletion ✅

See more in project data wiki

icav2 projectpipelines extensions

icav2 projectpipelines create-workflow-from-zip

Create a pipeline in an icav2 project from a zipped up CWL directory

• Autocompletion ✅

See more in project pipelines wiki

icav2 projectpipelines create-workflow-from-github-release

Create a pipeline in an icav2 project from a GitHub release

• Autocompletion ✅

See more in project pipelines wiki

icav2 projectpipelines create-wes-input-template

Inspired by cwl-ica-create-workflow-submission-template Create a WES input template ready for launch in ICAv2

• Autocompletion ✅

See more in project pipelines wiki

icav2 projectpipelines start-wes

Launch a CWL Workflow from a wes template

• Autocompletion ✅

See more in project pipelines wiki

icav2 projectpipelines release

Release a projectpipeline from the CLI

• Autocompletion ✅

See more in project pipelines wiki

icav2 projectanalyses extensions

icav2 projectanalyses get-cwl-analysis-input-json

Collect inputjson used by an analyses

• Autocompletion ✅

See more in project analyses wiki

icav2 projectanalyses get-cwl-analysis-output-json

Collect outputjson used by an analyses

• Autocompletion ✅

See more in project analyses wiki

icav2 projectanalyses list-analysis-steps

Inspired by ica-get-tasks-from-workflow-history
Collect all steps in a workflow run, useful for debugging

• Autocompletion ✅

See more in project analyses wiki

icav2 projectanalyses get-analysis-step-logs

Get logs of a step id for a workflow

• Autocompletion ✅

See more in project analyses wiki

icav2 projectanalyses gantt-plot

Generate a gantt chart for a workflow

• Autocompletion ✅

See more in project analyses wiki

---

Directory Layout

~/.icav2-cli-plugins/
├── config                    # INI-style profile configuration
├── bin/
│   ├── icav2                 # Python CLI wrapper (entry point)
│   └── _icav2                # Bundled icav2 binary
├── cache/
│   └── <profile_name>/
│       └── session.yaml      # Cached access token per profile
├── pyenv/                    # Python virtual environment
├── autocompletion/           # Bash/zsh completions
└── tenants/                  # Legacy tenant configs (preserved if present)

---

Coming soon

icav2 projectanalyses list-cwltool-step-components --step-name

List all available components to view for a cwltool step.

icav2 projectanalyses get-cwltool-step-components --step-name --component-name

View a component for a cwltool step