命令行界面 (CLI)

GitHub npm crates.io

API 参考

Tauri 通过强大的命令行参数解析器 clap 使您的应用程序能够拥有 CLI。您只需在 tauri.conf.json 文件中定义一个简单的 CLI 结构，即可定义您的接口，并在 JavaScript 和/或 Rust 中读取其参数匹配映射。

支持的平台

此插件需要 Rust 版本至少为 **1.77.2**

平台	级别	备注
Windows
Linux
macOS
Android
iOS

• Windows
  • 由于操作系统限制，生产应用默认无法将文本写回调用控制台。请查看 tauri#8305 以获取解决方法。

设置

安装 CLI 插件以开始使用。

自动

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

npm

npm run tauri add cli

yarn

yarn run tauri add cli

pnpm

pnpm tauri add cli

deno

deno task tauri add cli

bun

bun tauri add cli

cargo

cargo tauri add cli

手动

1. 在 src-tauri 文件夹中运行以下命令，将插件添加到项目的 Cargo.toml 依赖项中

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

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

   src-tauri/src/lib.rs

   #[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 访客绑定
   npm

   npm install @tauri-apps/plugin-cli

   yarn

   yarn add @tauri-apps/plugin-cli

   pnpm

   pnpm add @tauri-apps/plugin-cli

   deno

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

   bun

   bun add @tauri-apps/plugin-cli

基础配置

在 tauri.conf.json 中，您可以使用以下结构来配置接口：

src-tauri/tauri.conf.json

{
  "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"
            }
          ]
        }
      }
    }
  }
}

注意

此处所有 JSON 配置仅为示例，为清晰起见，省略了许多其他字段。

添加参数

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

位置参数

位置参数通过其在参数列表中的位置来标识。使用以下配置：

src-tauri/tauri.conf.json

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

用户可以运行您的应用程序，例如 ./app tauri.txt dest.txt，参数匹配映射将把 source 定义为 "tauri.txt"，把 destination 定义为 "dest.txt"。

命名参数

命名参数是 (键, 值) 对，其中键标识值。使用以下配置：

tauri-src/tauri.conf.json

{
  "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"]。

标志参数

标志参数是一个独立的键，其存在或缺失向应用程序提供信息。使用以下配置：

tauri-src/tauri.conf.json

{
  "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 数组定义额外的嵌套接口：

tauri-src/tauri.conf.json

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

其配置与根应用程序配置相同，包括 description、longDescription、args 等。

用法

CLI 插件在 JavaScript 和 Rust 中均可用。

JavaScript

import { getMatches } from '@tauri-apps/plugin-cli';
// when using `"withGlobalTauri": true`, you may use
// const { getMatches } = window.__TAURI__.cli;

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

Rust

src-tauri/src/lib.rs

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` here is a Struct with { args, subcommand }.
               // `args` is `HashMap<String, ArgData>` where `ArgData` is a struct with { value, occurrences }.
               // `subcommand` is `Option<Box<SubcommandMatches>>` where `SubcommandMatches` is a struct with { name, matches }.
               Ok(matches) => {
                   println!("{:?}", matches)
               }
               Err(_) => {}
           }
           Ok(())
       })
       .run(tauri::generate_context!())
       .expect("error while running tauri application");
}

权限

默认情况下，所有潜在危险的插件命令和范围都被阻止，无法访问。您必须修改 capabilities 配置中的权限才能启用这些功能。

有关更多信息，请参阅功能概述，并参阅分步指南以使用插件权限。

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": ["cli:default"]
}

默认权限

允许读取 CLI 匹配项

此默认权限集包括以下内容

• allow-cli-matches

权限表

标识符	描述
启用 cli_matches 命令，不带任何预配置范围。	cli:allow-cli-matches
禁用 cli_matches 命令，不带任何预配置范围。	cli:deny-cli-matches