命令行工具（bioctl）

Bio-OS提供以bioctl命令行工具的方式进行和Bio-OS控制面之间的通信。

安装方式

Step1 - 下载Bioctl

下载bioos github的release包（https://github.com/Bio-OS/bioos/releases）解压缩到本地。

Step2 - 配置Bioctl

1. 将bioctl二进制文件移动到可执行文件目录中，mac或者linux通常为 /usr/local/bin

2. 在User目录下新增 .bioctl文件夹，mac中通常为 /Users/用户名

# 创建./bioctl目录
mkdir /Users/用户名/.bioctl

1. 在.bioctl文件夹中新增 bioctl.yaml文件，并将一下代码复制到yaml文件中

client:
  serverAddr: xx.xx.xxx.xxx/apiserver
  serverName: localhost
  insecure: true
  username: admin
  password: admin
  method: http
  timeout: 10
```

1. 修改bioctl.yaml文件中的serverAddr中的IP地址(xx.xx.xxx.xxx)为你所部署的bio-os的server地址

2. 完成上述步骤后即可在命令行中执行： bioctl 并查看帮助信息

使用方式

Bioctl支持两种使用方式：交互式及命令行

1. 交互式：当输入特定命令组如 bioctl 或者 bioctl workspace 或者 bioctl workflow 或者 bioctl submission 或者bioctl datamodel 时，进入交互式模式，出现options供选择

2. 命令行：也可直接输入命令行如： bioctl workspace create <workspace_name> ，直接执行命令行

Workspace相关命令

Usage: bioctl workspace [OPTIONS] COMMAND [ARGS]...
Options:
-h, --help            show this help message and exit
  
Commands:
  Create <Workspace_name>     创建Workspace
    Options:
       -d, --description     输入Workspace描述
       -t, --mountType       指定挂载类型
       -p，--mountPATH        指定目录
       
       
  import      导入Workspace
    Options:
       -y, --yaml PATH     通过指定yaml文件路径创建Workspace
       -t, --mountType       指定挂载类型
       -p，--mountPATH        指定目录

  delete  <Workspace_name>    删除相指定Workspace,默认不删除数据
    Options:


  list        列出所有当前Workspace
    Options:
      -p, --page               分页页数，默认为1  
      -s, --size               分页大小，默认为10
      --order-by               以时间或名称进行升序排序所有Workspace（--order-by StartTime/Name）
      --search-word            workspace name/description中模糊匹配, OR
      --ids                    指定workspace id展示特定Workspace完整信息，包括名称、创建时间、挂载目录

  
  Update  <Workspace_name> 更新Workspace
      Options:
       -n，--name         输入将要修改的Workspace名称
       -d, --description  输入Workspace描述

导入Workspace

bioctl workspace import -y workspacexxx.yaml

workspacexxx.yaml示例

yaml中datamodel、workflow、notebook中path需相对yaml文件路径按下面示例中的path路径，文件夹组织路径举例如下：

|--workspacexxx.yaml

|--data

|--sample.csv

|--sample_sheet.csv

|--workspace_data.csv

|--workflow

|--Cram-to-Bam

|--CramToBam.wdl

|--notebook

|--__dashboard__.ipynb

|--First-Notebooks.ipynb

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

创建Workspace

bioctl workspace create <workspace_name> -d descriptionxxxx  -t  nfs  -p /path

删除Workspace

bioctl workspace delete <workspace_name>

列出Workspace

$ [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

工作流相关命令

Usage: bioctl workflow [OPTIONS] COMMAND [ARGS]...

Commands:
  create <workflow_name>     创建workflow工作流并命名为workflow_name
      -w, --workspace        （*）指定工作流所在Workspace
      -d, --description       输入Workflow描述
      --language              (*)输入Workflow的语言
      --url                  （*）git地址
      -d, --description      工作流描述
      --tag                  （*）git tag（或branch）
      --token                git token
      -p, --main-workflow-path  （*） 主工作流路径 
   
  import    以文件形式导入workspace的工作流
    Options:                
        -f, --file     （*）通过Json文件方式作为工作流输入
        -w, --workspace     （*）删除指定workspace下的工作流

  delete <worflow_name>   删除指定工作流
    Options:
        -w, --workspace     （*）删除指定workspace下的工作流
        
  list       无option则获取Workspace中的所有工作流
    Options:
        -w, --workspace    （*）列出指定workspace下的工作流
        -p, --page         分页页数，默认为1  
        -s, --size         分页大小，默认为10
        --order-by         以时间或名称进行升序排序所有Workspace（--order-by name/createdAt）
        --search-words         workflow name/description中模糊匹配, OR
        --ids              指定workflow id展示特定workflow完整信息，包括名称、创建时间、挂载目录
        
  update  <worflow_name>   更新指定工作流
      Options
         -w, --workspace      （*）指定工作流所在workspace
         -n, --name           更新指定工作流名称
         -d, --description    更新指定工作流描述        

创建工作流

bioctl workflow create myworkflow -w myworkspace -url https://github.com/jixinchi/example-wdl.git --tag 0.1 -p main.wdl

导入工作流

bioctl workflow import -w workspace_name -i /home/usr/workflow_git.json

列出工作流

#列出具体Workflow信息
$ bioctl workflow list <workflow_name> 
--------------
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

投递任务相关命令

Usage: bioctl submission [OPTIONS] COMMAND [ARGS]...

Commands:
  submit <workflow_name>     投递工作流
    Options:
        -w, --workspace          （*）指定投递的工作流所在Workspace
        -t, --type               （*）指定投递的文件类型
        -f, --file               （*）Inputs/outputs File Path
        -m, --datamodel           Datamodel 名称
        --data-model-rows         data-model具体row的id，不输入就是所有id
        --call-caching            是否callcache，默认为true
        -d，--description         投递描述
        
  list   
    Options:
        -w, --workspace   （*）指定投递所在Workspace
        -p, --page         分页页数，默认为1  
        -s, --size         分页大小，默认为10
        --order-by         以时间或名称进行升序排序所有Workspace（--order-by Name/StartTime）
        --search-word      submission name/description中模糊匹配, OR
        --status           查询指定状态的投递
        --ids              指定submission id展示特定submission完整信息，包括名称、创建时间、挂载目录
        
  query <submission_id>    查询投递状态
    Options:
        -w, --workspace          （*）指定投递所在Workspace
        -r, --run-id string       查询submission下特定run的状态
        -t, --task-name string    查询submission下特定task的状态

  stop   <submission_id>    终止投递如option指定run运行，则只终止单个运行
    Options:
        -w, --workspace           （*）指定投递所在Workspace
        -r, --run-id string        终止特定run-id的运行

  delete <submission_id>    删除投递历史
    Options:
        -w, --workspace          （*）指定投递所在Workspace
        
  log <submission_id>  查看投递日志
     Options: 
        -w, --workspace        （*）指定投递所在Workspace  
        -r, --run-id string     投递中的具体运行的日志
        -t, --task-name string 投递中的具体运行的task日志
        
  output <submission_id> 查看投递所有输出
     Options: 
        -w, --workspace        （*）指定投递所在Workspace    
        -r, --run-id string     指定投递的具体运行id

投递工作流

bioctl submission submit myworkflow -t  -f workflows/myworkflow/myworkflow.inputs.json -m sample -w demo

以下为输入输出文件的json格式

#input/Output json格式
{   
    "inputsTemplate": {
        "test.name1": "this.id-1",
        "test.name2": "this.1_id",
        "test.request": "this.id-2"
    },
    "outputsTemplate": {
        
    }
}

终止投递

##终止某个投递
bioctl submission stop --submission_id xxx -w workspaceidxxx
##终止某个工作流运行
bioctl submission stop --submission_id xxx --run_id xxx workspaceidxxx

查询运行状态

bioctl submission query <submission_id> -w workspaceidxxx

+----------+--------------------------+--------------------------------------+------------+
| 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  |
+----------+--------------------------+--------------------------------------+------------+

查询运行输出文件

bioctl submission output <submission_id> 

输出类似, 如果是字符则显示字符串，如果是文件则提供文件地址

[
        {
                "Path": "id",
                "Value": "50f65c11-acc3-4d8a-8f66-fab1f136f17c"
        },
        {
                "Path": "outputs.hello.out",
                "Value": "S3://....../...../"
        }
]

数据模型相关命令

Usage: bioctl datamodel [OPTIONS] COMMAND [ARGS]...

Commands:
  import    导入数据模型
    Options:
        -w, --workspace     （*）导入到指定workspace
        -i, --inputsFile    （*）导入的数据模型文件（必须csv格式）

  delete <datamodel_name>   删除指定Workspace下Datamodel
    Options:
        -w, --workspace   （*）指定workspace名称

  list      列出Workspace下所有Datamodel
    Options:
        -w, --workspace      指定导入的workspace
        -n, --name           列出具体名称的Datamodel的内容, 此时types失效（仅展示前100行）
        -t, --types          根据具体类型进行筛选，entity_set, entity, workspace