5 CLI

  3 分钟阅读  

原文链接: https://tauri.app/plugin/cli/

Tauri 通过 clap（一个健壮的命令行参数解析器）让你的应用拥有 CLI。只要在 tauri.conf.json 文件中简单地定义 CLI，你就可以定义自己的接口，并在 JavaScript 和／或 Rust 中读取它的参数匹配映射。

  • Windows
    • 由于操作系统限制，生产应用默认无法把文本写回调用它的控制台。变通办法请见 tauri#8305。

支持的平台

平台支持程度说明
Windows完整支持
Linux完整支持
macOS完整支持
Android不支持
iOS不支持

设置

自动

使用你的项目包管理器添加依赖：

1

npm run tauri add cli

1

yarn run tauri add cli

1

pnpm tauri add cli

1

deno task tauri add cli

1

bun tauri add cli

1

cargo tauri add cli

手动

  1. 在 src-tauri 文件夹中运行以下命令，把插件加入 Cargo.toml 里的项目依赖：

    1

    cargo add tauri-plugin-cli --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

  2. 修改 lib.rs 初始化插件：

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

    #[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            #[cfg(desktop)]
            app.handle().plugin(tauri_plugin_cli::init());
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

  3. 用你偏好的 JavaScript 包管理器安装 JavaScript 端绑定：

1

npm install @tauri-apps/plugin-cli

1

yarn add @tauri-apps/plugin-cli

1

pnpm add @tauri-apps/plugin-cli

1

deno add npm:@tauri-apps/plugin-cli

1

bun add @tauri-apps/plugin-cli

基础配置

在 tauri.conf.json 下，你可以用以下结构配置该接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "plugins": {
    "cli": {
      "description": "Tauri CLI Plugin Example",
      "args": [
        {
          "short": "v",
          "name": "verbose",
          "description": "Verbosity level"
        }
      ],
      "subcommands": {
        "run": {
          "description": "Run the application",
          "args": [
            {
              "name": "debug",
              "description": "Run application in debug mode"
            },
            {
              "name": "release",
              "description": "Run application in release mode"
            }
          ]
        }
      }
    }
  }
}

添加参数

args 数组表示其所属命令或子命令接受的参数列表。

位置参数

位置参数由它在参数列表中的位置来识别。使用以下配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "args": [
    {
      "name": "source",
      "index": 1,
      "takesValue": true
    },
    {
      "name": "destination",
      "index": 2,
      "takesValue": true
    }
  ]
}

用户可以以 ./app tauri.txt dest.txt 运行你的应用，参数匹配映射会把 source 定义为 "tauri.txt"，把 destination 定义为 "dest.txt"。

具名参数

具名参数是一个（键, 值）对，其中键用来标识该值。使用以下配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "args": [
    {
      "name": "type",
      "short": "t",
      "takesValue": true,
      "multiple": true,
      "possibleValues": ["foo", "bar"]
    }
  ]
}

用户可以以 ./app --type foo bar、./app -t foo -t bar 或 ./app --type=foo,bar 运行你的应用，参数匹配映射会把 type 定义为 ["foo", "bar"]。

标志参数

标志参数是一个独立的键，它的出现与否为你的应用提供信息。使用以下配置：

1
2
3
4
5
6
7
8

{
  "args": [
    {
      "name": "verbose",
      "short": "v"
    }
  ]
}

用户可以以 ./app -v -v -v、./app --verbose --verbose --verbose 或 ./app -vvv 运行你的应用，参数匹配映射会把 verbose 定义为 true，且 occurrences = 3。

子命令

有些 CLI 应用还有作为子命令的附加接口。例如 git CLI 有 git branch、git commit 和 git push。你可以用 subcommands 数组定义额外的嵌套接口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "cli": {
    ...
    "subcommands": {
      "branch": {
        "args": []
      },
      "push": {
        "args": []
      }
    }
  }
}

它的配置与根应用配置相同，包含 description、longDescription、args 等。

用法

CLI 插件在 JavaScript 和 Rust 中都可以使用。

语言

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

import { getMatches } from '@tauri-apps/plugin-cli';
// 使用 `"withGlobalTauri": true` 时，你可以这样写
// const { getMatches } = window.__TAURI__.cli;

const matches = await getMatches();
if (matches.subcommand?.name === 'run') {
  // 执行了 `./your-app run $ARGS`
  const args = matches.subcommand.matches.args;
  if (args.debug?.value === true) {
    // 执行了 `./your-app run --debug`
  }
  if (args.release?.value === true) {
    // 执行了 `./your-app run --release`
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

use tauri_plugin_cli::CliExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
   tauri::Builder::default()
       .plugin(tauri_plugin_cli::init())
       .setup(|app| {
           match app.cli().matches() {
               // 这里的 `matches` 是包含 { args, subcommand } 的结构体。
               // `args` 是 `HashMap<String, ArgData>`，`ArgData` 是含 { value, occurrences } 的结构体。
               // `subcommand` 是 `Option<Box<SubcommandMatches>>`，`SubcommandMatches` 是含 { name, matches } 的结构体。
               Ok(matches) => {
                   println!("{:?}", matches)
               }
               Err(_) => {}
           }
           Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
}

权限

默认情况下，所有有潜在危险的插件命令和作用域都被阻止，无法访问。你必须在 capabilities 配置中修改权限才能启用它们。

更多信息请参阅能力概述，以及使用插件权限的分步指南。

1
2
3
4
5
6
7

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": ["cli:default"]
}
最后修改 September 26, 2026: 更新 (630b11f59)