# 命令行工具（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 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://bio-os.gitbook.io/userguide/chan-pin-zhi-nan/ming-ling-xing-gong-ju-bioctl.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.