> For the complete documentation index, see [llms.txt](https://bio-os.gitbook.io/bio-os-open-source-version-user-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bio-os.gitbook.io/bio-os-open-source-version-user-manual/product-manual/cli-tool-bioctl.md). # CLI Tool（bioctl） Bio-OS provides the **bioctl** command-line tool for communication with the Bio-OS control plane. ## Installation **Step1 - Download Bioctl** Download the Bio-OS release package from GitHub ([https://github.com/Bio-OS/bioos/releases](https://github.com/Bio-OS/bioos/releases?utm_source=chatgpt.com)) and extract it locally. **Step2 - Bioctl Config** 1. Move the **bioctl** binary to the executable directory, which is typically `/usr/local/bin` on macOS or Linux. 2. Create a **.bioctl** folder in the User directory, which on macOS is typically located at `/Users/username`. ```sh # Create the ./bioctl directory mkdir /Users/username/.bioctl ``` 3. In the **.bioctl** folder, create a **bioctl.yaml** file and copy the following code into the YAML file. ````yaml client: serverAddr: xx.xx.xxx.xxx/apiserver serverName: localhost insecure: true username: admin password: admin method: http timeout: 10 ``` ```` 4. In the **bioctl.yaml** file, change the `serverAddr` IP address (`xx.xx.xxx.xxx`) to the server address of your deployed Bio-OS. 5. After completing the above steps, you can run `bioctl` in the command line and view the help information. ## Usage Bioctl supports two usage modes: **interactive** and **command-line**. * **Interactive**: When you enter certain command groups (e.g., `bioctl`, `bioctl workspace`, `bioctl workflow`, `bioctl submission`, or `bioctl datamodel`), Bioctl enters interactive mode and displays options to choose from. * **Command-line**: You can also execute commands directly, for example: ```bash bioctl workspace create ``` to run the command immediately. ## Workspace Commands {% code lineNumbers="true" %} ``` Usage: bioctl workspace [OPTIONS] COMMAND [ARGS]... Options: -h, --help show this help message and exit Commands: Create Create workspace Options: -d, --description -t, --mountType -p，--mountPATH import Import workspace Options: -y, --yaml PATH -t, --mountType -p，--mountPATH delete Delete workspace Options: list List orkspace Options: -p, --page -s, --size --order-by --search-word --ids Update Update workspace Options: -n，--name -d, --description ``` {% endcode %} ### Import Workspace ```Plain bioctl workspace import -y workspacexxx.yaml ``` workspacexxx.yaml demo In the YAML file, the `path` values for `datamodel`, `workflow`, and `notebook` must be specified relative to the location of the YAML file. An example of folder organization is shown below: \|--workspacexxx.yaml \|--data \|--sample.csv \|--sample\_sheet.csv \|--workspace\_data.csv \|--workflow \|--Cram-to-Bam \|--CramToBam.wdl \|--notebook \|--\_\_dashboard\_\_.ipynb \|--First-Notebooks.ipynb ```JSON name: Workspacexxx version: "1" description: Demo dataModels: - name: sample type: entity path: data/sample.csv - name: sample_set type: entitySet path: data/sample_set.csv - name: workspace_data type: workspace path: data/workspace_data.csv workflows: - name: Cram-to-Bam language: WDL version: "1.0" mainWorkflowPath: CramToBam.wdl path: workflow/Cram-to-Bam metadata: scheme: https repo: gitee.com/joy_lee/seq-format-conversion01 tag: v0.47 - name: GATK-HaplotypeCaller language: WDL version: "1.0" mainWorkflowPath: Hello-GATK.wdl path: workflow/GATK-HaplotypeCaller metadata: scheme: https repo: gitee.com/joy_lee/gatk-pipeline tag: v0.34 notebooks: image: name: paas-tob-qa-cn-shanghai.cr.volces.com/infcprelease/jupyterhub-datascience-notebook:miracle-1.4.1 disPlayName: datascience packages: '{"R": {"DT": "0.20", "R6": "2.5.1", "fs": "1.5.0", "gh": "1.3.0", "ps": "1.6.0", "DBI": "1.1.1", "TTR": "0.24.2", "bit": "4.0.4", "cli": "3.1.0", "hms": "1.1.1", "ids": "1.0.1", "ini": "0.3.1", "lhs": "1.1.3", "rex": "1.2.0", "sys": "3.4", "xts": "0.12.1", "zip": "2.2.0", "zoo": "1.8-9", "MASS": "7.3-54", "Rcpp": "1.0.7", "base": "4.1.1", "blob": "1.2.2", "brew": "1.0-6", "brio": "1.1.2", "covr": "3.5.1", "curl": "4.3.2", "desc": "1.4.0", "gert": "1.4.3", "glue": "1.5.0", "grid": "4.1.1", "httr": "1.4.2"}}' basicEnv: - Python3.9.10 - R 4.1.2 - Julia 1.7.2 artifacts: - name: __dashboard__ path: notebook/__dashboard__.ipynb - name: First-Notebooks path: notebook/First-Notebooks.ipynb ``` ### Create Workspace ```Plain bioctl workspace create -d descriptionxxxx -t nfs -p /path ``` ### Delete Workspace ```undefined bioctl workspace delete ``` ### List Workspace ```undefined $ [admin@bioos]bioctl workspace list --order-by time WorkspaceName WorkspaceID CreateTime Mounttype MountPath xxxxx XXXXXX 2022-09-09 01:15:26.394 +0000 $ [admin@bioos]bioctl workspace list --search-word xxxxx WorkspaceName WorkspaceID CreateTime Mounttype MountPath xxxxx XXXXXX 2022-09-09 01:15:26.394 +0000 ``` ## Workflow Commands ```JSON Usage: bioctl workflow [OPTIONS] COMMAND [ARGS]... Commands: create -w, --workspace -d, --description --language --url -d, --description --tag --token -p, --main-workflow-path import 以文件形式导入workspace的工作流 Options: -f, --file -w, --workspace delete Options: -w, --workspace list Options: -w, --workspace -p, --page -s, --size --order-by --search-words --ids update Options -w, --workspace -n, --name -d, --description ```
### Create workflow ```Plain bioctl workflow create myworkflow -w myworkspace -url https://github.com/jixinchi/example-wdl.git --tag 0.1 -p main.wdl ``` ### Import workflow ```Plain bioctl workflow import -w workspace_name -i /home/usr/workflow_git.json ``` ### List workflow ```Plain #list Workflow metadata $ bioctl workflow list -------------- workflow : workflow_name -------------- WorkflowID: description: xxxxxxxxxx Create time: 2022-09-09 01:15:26.394 +0000 Git Address: $ bioctl workflow list -w workspace_name Worflow_name WorkflowID Create_date WorkflowA 2022-09-09 01:15:26.394 +0000 WorkflowB 2022-09-09 01:15:26.394 +0000 ``` ## Submission Commands ```JSON Usage: bioctl submission [OPTIONS] COMMAND [ARGS]... Commands: submit Options: -w, --workspace -t, --type -f, --file -m, --datamodel --data-model-rows --call-caching -d，--description list Options: -w, --workspace -p, --page -s, --size --order-by --search-word --status --ids query Options: -w, --workspace -r, --run-id string -t, --task-name string stop Options: -w, --workspace -r, --run-id string delete Options: -w, --workspace log Options: -w, --workspace -r, --run-id string -t, --task-name string output Options: -w, --workspace -r, --run-id string ``` ### Submit workflow ```undefined bioctl submission submit myworkflow -t -f workflows/myworkflow/myworkflow.inputs.json -m sample -w demo ``` The following is the JSON format for input and output files ```Plain # input/Output json format { "inputsTemplate": { "test.name1": "this.id-1", "test.name2": "this.1_id", "test.request": "this.id-2" }, "outputsTemplate": { } } ``` ### Terminate workflow ```Plain ## Terminate a submission bioctl submission stop --submission_id xxx -w workspaceidxxx ## Terminate a workflow run bioctl submission stop --submission_id xxx --run_id xxx workspaceidxxx ``` ### Query submission status ```Plain bioctl submission query -w workspaceidxxx ``` ```SQL +----------+--------------------------+--------------------------------------+------------+ | RUN ID | CREATE TIME | RUN STATUS | +----------+--------------------------+--------------------------------------+------------+ | 87546541-f41d-4745-9d1e-4b9b0f27b033 | 2020-10-21T06:34:10.859Z | Running | | cc195aee-41c7-44b0-89e5-4e94ba47f56b | 2020-10-21T05:52:28.360Z | Succeeded | | 7209675e-4277-4d68-8848-725abca6b143 | 2020-10-21T05:52:08.340Z | Succeeded | | 05ed1979-39d4-41db-8535-446919088a2b | 2020-10-21T03:50:01.010Z | Succeeded | | b2394c34-9086-441f-af49-02735b5710ed | 2020-10-21T03:45:40.783Z | Succeeded | +----------+--------------------------+--------------------------------------+------------+ ``` ### Query submission outputs ```Plain bioctl submission output ``` The output follows this rule: if the value is a string, the content is displayed directly; if it is a file, the corresponding file path is provided. ```JSON [ { "Path": "id", "Value": "50f65c11-acc3-4d8a-8f66-fab1f136f17c" }, { "Path": "outputs.hello.out", "Value": "S3://....../...../" } ] ```
## Datamodel Commands ```JSON Usage: bioctl datamodel [OPTIONS] COMMAND [ARGS]... Commands: import import datamodels Options: -w, --workspace -i, --inputsFile delete delete datamodels Options: -w, --workspace list list datamodels in the workspace Options: -w, --workspace -n, --name -t, --types ```