# imagegp-cli

**Repository Path**: ct5869/imagegp-cli

## Basic Information

- **Project Name**: imagegp-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImageGP CLI

`imagegp` is a local, cross-platform HTTP client for ImageGP. Its `--server` value is the ImageGP API base URL, not only the domain name. It uploads local inputs through the API, submits an analysis, polls the asynchronous task, downloads a ZIP artifact bundle, and writes it to a local output folder.

The analysis itself runs on the [ImageGP](https://www.bic.ac.cn/BIC/) server.

## Install

Choose one of the following methods to install `imagegp`:

### Install from PyPI

```bash
pip install imagegp-cli
```

### Install from GitHub

```bash
pip install ""git+https://github.com/Tong-Chen/imagegp-cli.git""
```

### Install from Gitee

```bash
pip install "git+https://gitee.com/ct5869/imagegp-cli.git"
```

### Install from source

```bash
git clone https://github.com/Tong-Chen/imagegp-cli.git
cd imagegp-cli
python -m pip install .
```

## CLI usage

### Simple test

```bash
imagegp --help
imagegp tools list
```

### Normal useage

The current server login contract expects the password digest used by the Web client. Register at <https://www.bic.ac.cn/BIC/#/userManage>. `imagegp login` hashes the interactive password with MD5 by default. Use `--password-digest` when supplying an already-generated digest.

CLI run, upload, status, and download operations require an authenticated user.

```bash
# Login interactively and let the CLI store the token in the system keychain
imagegp login
# Input user email and password interactively

# Logout when needed
imagegp logout
```

#### Version check

```bash
imagegp version
```

#### List tools

```bash
imagegp tools list
```

Normally you could get (Only list first 6 tools):

```text
1       tool    Boxplot
2       tool    Flower plot
3       tool    Line plot
4       tool    Long to wide matrix
5       tool    Merge matrixes
6       tool    Pretty heatmap
```

#### Generate a config template

```bash
# Pay attention to the double quotes, needed especially for tool names with spaces like "Flower plot"
imagegp config init --tool "Boxplot" --output boxplot.yaml
# Force to replace an existing template
imagegp config init --tool "Boxplot" --output boxplot.yaml --force
```

In `examples` folder, there are some demo yaml files, serving as config templates with demo parameters and input files.

#### Run a tool

```bash
# Users should prepare input files in the input directory and modify the config file before running
imagegp run --config boxplot.yaml --input-dir ./input --output-dir ./result
```

#### Run a tool with a demo

More fesible way is to run a tool with a demo.

```bash
imagegp config init --tool "Boxplot" --demo Demo1 --output boxplot-demo1.yaml
imagegp run --config boxplot-demo1.yaml --input-dir ./input --output-dir ./result

# Would generate outputs like
# status=SUCCESS
# output_dir=/Users/ct/github/imagegp-cli/examples/result/run/artifacts/Boxplot_20260805_143210_42
```

By default, a run stores only the downloaded result files below
`result/run/artifacts/`. If the analysis fails, the CLI automatically attempts
to download the server log as if `--keep-log` had been specified. For a
successful run, use `--keep-log` to retain the log explicitly.

Each run is stored in a tool-and-timestamp directory under `artifacts`, while
any parent directories inside the server ZIP are preserved:

```text
result/run/artifacts/Boxplot_20260805_143210_42/
└── plot/result.png
```

#### Run another tool with a demo

```bash
imagegp config init --tool "WGCNA" --demo Demo1 --output WGCNA-demo1.yaml
imagegp run --config WGCNA-demo1.yaml --input-dir ./input --output-dir ./result

# Would generate outputs like
# status=SUCCESS
# output_dir=/Users/ct/github/imagegp-cli/examples/result/run/artifacts/WGCNA_20260805_143210_43
```

### The config template

Use the server-side tool metadata to generate an editable YAML template:

```bash
imagegp tools list --query boxplot
imagegp config init --tool 1 --output boxplot.yaml
```

To initialize from a server-provided demo, including its parameter values and
example input files, use `--demo`:

```bash
imagegp config init --tool 1 --demo Demo1 --output boxplot-demo.yaml
```

Demo text inputs are written into the generated config's input directory. Demo
files referenced by the server are downloaded there. Use `--force` to replace
existing demo files and the existing template.

The command fills in the tool ID, input slots, parameter defaults, input/output
directories, and runtime settings. It also includes all `cascadeSelect` and
`multipleSelect` parameters, their cascade relationships, and static choices
under `_template_help`. Data-dependent choices are described there as coming
from the columns or unique values of the selected input data. Parameters are
shown under `params.required` and `params.optional` to make the template easier
to complete:

```yaml
params:
  required:
    X_variable: ""
  optional:
    color_variable: ""
```

Before submission, `imagegp run` flattens these two sections into the API
payload. Existing templates with a flat `params` mapping remain supported.
Edit the generated `inputs` paths and empty variable/required values before
running:

```bash
imagegp run --config boxplot.yaml
```

Use `--force` to replace an existing template. A `.json` output path generates
JSON instead of YAML:

```bash
imagegp config init --tool 17 --output boxplot.json --force
```

Use `--json-output` for automation. It writes a machine-readable run summary
to stdout; it does not cause `result.json` or the server `manifest.json` to be
created locally. The local `result/run/manifest.json` contains only status and
run identifiers, not the submitted parameter values.

To keep the server log for debugging:

```bash
imagegp run --config boxplot.yaml --keep-log
```

## Chinese language support

Command-line prompts support Chinese and English. English is the default. Set the language before the subcommand, or configure it through the environment:

```bash
export IMAGEGP_LANGUAGE=zh
imagegp --help

# or
imagegp --lang zh tools list
```

`--lang` is an alias for `--language`; accepted values are `zh` and `en`.

JSON output field names remain unchanged regardless of the selected language.

## Optional operations

These operations are not always required.

### Authentication token and environment variables

You can also provide the token through the environment:

```bash
export IMAGEGP_TOKEN='...'
export IMAGEGP_SERVER='https://www.bic.ac.cn/Cloud_Platform_API'
```

Windows PowerShell:

```powershell
$env:IMAGEGP_TOKEN = '...'
$env:IMAGEGP_SERVER = 'https://www.bic.ac.cn/Cloud_Platform_API'
```

### Development install

```bash
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\\Scripts\\activate
python -m pip install -e .
```