命令行接口 (CLI)

GitHub npm crates.io

API Reference

Tauri 通过 clap 让你的应用拥有 CLI，这是一个强大的命令行参数解析器。在你的 tauri.conf.json 文件中使用简单的 CLI 定义，你可以定义你的界面并在 JavaScript 和/或 Rust 中读取它的参数匹配映射。

🌐 Tauri enables your app to have a CLI through clap, a robust command line argument parser. With a simple CLI definition in your tauri.conf.json file, you can define your interface and read its argument matches map on JavaScript and/or Rust.

支持的平台

🌐 Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

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

设置

🌐 Setup

安装 CLI 插件以开始使用。

🌐 Install the CLI plugin to get started.

Automatic

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

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

Manual

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 Guest 绑定：
   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

基本配置

🌐 Base Configuration

在 tauri.conf.json 下，你有以下结构来配置接口：

🌐 Under tauri.conf.json, you have the following structure to configure the interface:

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

Note

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

🌐 All JSON configurations here are just samples, many other fields have been omitted for the sake of clarity.

添加参数

🌐 Adding Arguments

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

🌐 The args array represents the list of arguments accepted by its command or subcommand.

位置参数

🌐 Positional Arguments

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

🌐 A positional argument is identified by its position in the list of arguments. With the following configuration:

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

🌐 Users can run your app as ./app tauri.txt dest.txt and the arg matches map will define source as "tauri.txt" and destination as "dest.txt".

命名参数

🌐 Named Arguments

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

🌐 A named argument is a (key, value) pair where the key identifies the value. With the following configuration:

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

🌐 Users can run your app as ./app --type foo bar, ./app -t foo -t bar or ./app --type=foo,bar and the arg matches map will define type as ["foo", "bar"].

标记参数

🌐 Flag Arguments

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

🌐 A flag argument is a standalone key whose presence or absence provides information to your application. With the following configuration:

tauri-src/tauri.conf.json

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

用户可以以 ./app -v -v -v、./app --verbose --verbose --verbose 或 ./app -vvv 的身份运行你的应用，而参数匹配映射将定义 verbose 为 true，并带有 occurrences = 3。

🌐 Users can run your app as ./app -v -v -v, ./app --verbose --verbose --verbose or ./app -vvv and the arg matches map will define verbose as true, with occurrences = 3.

子命令

🌐 Subcommands

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

🌐 Some CLI applications have additional interfaces as subcommands. For instance, the git CLI has git branch, git commit and git push. You can define additional nested interfaces with the subcommands array:

tauri-src/tauri.conf.json

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

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

🌐 Its configuration is the same as the root application configuration, with the description, longDescription, args, etc.

使用

🌐 Usage

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

🌐 The CLI plugin is available in both JavaScript and 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");
}

权限

🌐 Permissions

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

🌐 By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

有关更多信息，请参见功能概览，有关使用插件权限的分步指南，请参见分步指南。

🌐 See the Capabilities Overview for more information and the step by step guide to use plugin permissions.

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

Default Permission

Allows reading the CLI matches

This default permission set includes the following:

• allow-cli-matches

Permission Table

Identifier	Description
cli:allow-cli-matches	Enables the cli_matches command without any pre-configured scope.
cli:deny-cli-matches	Denies the cli_matches command without any pre-configured scope.