# 命令行工具（bioctl） #### Bio-OS提供以bioctl命令行工具的方式进行和Bio-OS控制面之间的通信。 ## 安装方式 **Step1 - 下载Bioctl** 下载bioos github的release包（[**https://github.com/Bio-OS/bioos/releases**](https://github.com/Bio-OS/bioos/releases)）解压缩到本地。 **Step2 - 配置Bioctl** 1. 将bioctl二进制文件移动到可执行文件目录中，mac或者linux通常为 /usr/local/bin 2. 在User目录下新增 .bioctl文件夹，mac中通常为 /Users/用户名 ```sh # 创建./bioctl目录 mkdir /Users/用户名/.bioctl ``` 3. 在.bioctl文件夹中新增 bioctl.yaml文件，并将一下代码复制到yaml文件中 ````yaml client: serverAddr: xx.xx.xxx.xxx/apiserver serverName: localhost insecure: true username: admin password: admin method: http timeout: 10 ``` ```` 4. 修改bioctl.yaml文件中的serverAddr中的IP地址(xx.xx.xxx.xxx)为你所部署的bio-os的server地址 5. 完成上述步骤后即可在命令行中执行： bioctl 并查看帮助信息 ## 使用方式 Bioctl支持两种使用方式：交互式及命令行 1. 交互式：当输入特定命令组如 bioctl 或者 bioctl workspace 或者 bioctl workflow 或者 bioctl submission 或者bioctl datamodel 时，进入交互式模式，出现options供选择 2. 命令行：也可直接输入命令行如： bioctl workspace create \ ，直接执行命令行 ## Workspace相关命令 {% code lineNumbers="true" %} ``` Usage: bioctl workspace [OPTIONS] COMMAND [ARGS]... Options: -h, --help show this help message and exit Commands: Create 创建Workspace Options: -d, --description 输入Workspace描述 -t, --mountType 指定挂载类型 -p，--mountPATH 指定目录 import 导入Workspace Options: -y, --yaml PATH 通过指定yaml文件路径创建Workspace -t, --mountType 指定挂载类型 -p，--mountPATH 指定目录 delete 删除相指定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 Options: -n，--name 输入将要修改的Workspace名称 -d, --description 输入Workspace描述 ``` {% endcode %} ### 导入Workspace ```Plain 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 ```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 ``` ### 创建Workspace ```Plain bioctl workspace create -d descriptionxxxx -t nfs -p /path ``` ### 删除Workspace ```undefined bioctl workspace delete ``` ### 列出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 ``` ## 工作流相关命令 ```JSON Usage: bioctl workflow [OPTIONS] COMMAND [ARGS]... Commands: create 创建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 删除指定工作流 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 更新指定工作流 Options -w, --workspace （*）指定工作流所在workspace -n, --name 更新指定工作流名称 -d, --description 更新指定工作流描述 ```
### 创建工作流 ```Plain bioctl workflow create myworkflow -w myworkspace -url https://github.com/jixinchi/example-wdl.git --tag 0.1 -p main.wdl ``` ### 导入工作流 ```Plain bioctl workflow import -w workspace_name -i /home/usr/workflow_git.json ``` ### 列出工作流 ```Plain #列出具体Workflow信息 $ 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 ``` ## 投递任务相关命令 ```JSON Usage: bioctl submission [OPTIONS] COMMAND [ARGS]... Commands: submit 投递工作流 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 查询投递状态 Options: -w, --workspace （*）指定投递所在Workspace -r, --run-id string 查询submission下特定run的状态 -t, --task-name string 查询submission下特定task的状态 stop 终止投递如option指定run运行，则只终止单个运行 Options: -w, --workspace （*）指定投递所在Workspace -r, --run-id string 终止特定run-id的运行 delete 删除投递历史 Options: -w, --workspace （*）指定投递所在Workspace log 查看投递日志 Options: -w, --workspace （*）指定投递所在Workspace -r, --run-id string 投递中的具体运行的日志 -t, --task-name string 投递中的具体运行的task日志 output 查看投递所有输出 Options: -w, --workspace （*）指定投递所在Workspace -r, --run-id string 指定投递的具体运行id ``` ### 投递工作流 ```undefined bioctl submission submit myworkflow -t -f workflows/myworkflow/myworkflow.inputs.json -m sample -w demo ``` 以下为输入输出文件的json格式 ```Plain #input/Output json格式 { "inputsTemplate": { "test.name1": "this.id-1", "test.name2": "this.1_id", "test.request": "this.id-2" }, "outputsTemplate": { } } ``` ### 终止投递 ```Plain ##终止某个投递 bioctl submission stop --submission_id xxx -w workspaceidxxx ##终止某个工作流运行 bioctl submission stop --submission_id xxx --run_id xxx workspaceidxxx ``` ### 查询运行状态 ```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 | +----------+--------------------------+--------------------------------------+------------+ ``` ### 查询运行输出文件 ```Plain bioctl submission output ``` 输出类似, 如果是字符则显示字符串，如果是文件则提供文件地址 ```JSON [ { "Path": "id", "Value": "50f65c11-acc3-4d8a-8f66-fab1f136f17c" }, { "Path": "outputs.hello.out", "Value": "S3://....../...../" } ] ```
## 数据模型相关命令 ```JSON Usage: bioctl datamodel [OPTIONS] COMMAND [ARGS]... Commands: import 导入数据模型 Options: -w, --workspace （*）导入到指定workspace -i, --inputsFile （*）导入的数据模型文件（必须csv格式） delete 删除指定Workspace下Datamodel Options: -w, --workspace （*）指定workspace名称 list 列出Workspace下所有Datamodel Options: -w, --workspace 指定导入的workspace -n, --name 列出具体名称的Datamodel的内容, 此时types失效（仅展示前100行） -t, --types 根据具体类型进行筛选，entity_set, entity, workspace ```