fz-mirrors/MaaAssistantArknights
0
0
Fork 0
mirror of https://github.com/MaaAssistantArknights/MaaAssistantArknights.git synced 2026-07-19 18:47:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: bump maa-cli to 0.5.8 (#14032)

Browse Source
This commit is contained in:
Loong
2025-09-08 15:30:02 +08:00
committed by GitHub
parent d54c857e5b
commit 80e34aba4d
12 changed files with 163 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
docs/en-us/manual/cli/config.md
View File

@@ -28,7 +28,7 @@ type = "StartUp" # The type of the task
params = { client_type = "Official", start_game_enabled = true } # The parameters of the task
```
The specific task types and parameters can be found in the [MAA Integration Document][task-types]. Note that maa-cli does not validate parameter names and values, and no error message will be generated even if an error occurs unless MaaCore detects an error at runtime.
The specific task types and parameters can be found in the [MAA Integration Document][task-types]. Note that maa-cli does not validate parameter names and values, and no error message will be generated even if an error occurs unless MaaCore` detects an error at runtime.
### Task variants and conditions
@@ -61,9 +61,9 @@ params = { plan_index = 2 }
The `condition` field is used to determine whether the variant should be used,
and the `params` field of the matched variant will be merged into the parameters of the task.
**Note**: If the `filename` field is a relative path, it will be relative to `$MAA_CONFIG_DIR/infrast`. Additionally, the custom infrastructure plan file will not be read by `maa-cli` but by MaaCore. Therefore, the file format must be `JSON` and the time period defined in the file will not be used to select the corresponding sub-plan. You must specify the `plan_index` field in the task parameters to use the correct infrastructure plan in the corresponding time period. This ensures that the correct infrastructure plan is used at the appropriate time.
**Note**: If the `filename` field is a relative path, it will be relative to `$MAA_CONFIG_DIR/infrast`. Besides, the custom infrastructure plan file will not be read by `maa-cli` but MaaCore. So the format of the file must be `JSON` and the time period defined in the file will not be used to select the corresponding sub-plan. So you must specify the `plan_index` field in the parameters of the task to use the correct infrastructure plan in the corresponding time period. This will ensure that the correct infrastructure plan is used in the appropriate time period.
Besides the `Time` condition, there are also `DateTime`, `Weekday`, and `DayMod` conditions.
Besides of `Time` condition, there are also `DateTime`, `Weekday`, `DayMod` conditions.
`DateTime` condition is used to specify a specific date-time period,
`Weekday` condition is used to specify some days in a week,
`DayMod` condition is similar to `Weekday`, but the period can be specified by `divisor` and `remainder`.
@@ -85,13 +85,13 @@ params = { stage = "CE-6" }
params = { stage = "1-7" }
```
All the above conditions related to time have a `timezone` field, which can be an offset from UTC (e.g., `8` for UTC+8) or a client type (e.g., `"Official"`). Note that the official server timezone is UTC+4, not UTC+8, because the game day starts at 04:00:00 rather than 00:00:00. If timezone is omitted, your local system timezone is used.
All the above conditions related to time have a `timezone` field, which is used to specify the timezone of the condition. The value of `timezone` can be an offset of UTC, like `8` or `-7`, or a name of the client type of game, like `Official`. Note, even though the official server is in China, the timezone of the official server is `UTC+4` instead of `UTC+8`, because the start of the game day is `04:00:00` instead of `00:00:00`. When the `timezone` is omitted, the condition will be matched in the local timezone of the system.
Besides of above conditions, there is a condition `OnSideStory` which depends on hot update resource to check if there is any opening side story. Thus, the condition of fight `SL-8` can be simplified as `{ type = "OnSideStory", client = "Official" }`, where the `client` is the client type of game.
In addition to the above conditions, there's a `OnSideStory` condition that uses hot-update resources to check if there are any active events. For example, the condition to farm `SL-8` during a summer event can be simplified to `{ type = "OnSideStory", client = "Official" }`, where `client` is your game client type. Using this condition means you only need to update the stage to farm when an event changes, without manually editing event dates.
Beside of above basic condition, `{ type = "And", conditions = [...] }` `{ type = "Or", conditions = [...] }`, and `{ type = "Not", condition = ... }` can be used for logical combination of conditions.
Besides the basic conditions, you can use `{ type = "And", conditions = [...] }`, `{ type = "Or", conditions = [...] }`, and `{ type = "Not", condition = ... }` for logical combinations.
By combining these conditions, you can define infrastructure plans spanning multiple days. Here's an example of 6 plans for 2 days:
By the combination of of above conditions, you can define an infrastructure plan for multiple days,
here is an example of 6 plans for 2 days:
```toml
[[tasks]]
@@ -109,14 +109,16 @@ filename = "normal.json"
condition = {
type = "And",
conditions = [
# The divisor specifies the period, the remainder specifies the offset
# The offset equals num_days_since_ce % divisor
# num_days_since_ce is the number of days since Common Era (0001-01-01 is day 1)
# You can get the current day's offset with `maa remainder <divisor>`
# For 2024-01-27, num_days_since_ce is 738,912
# The offset is 738,912 % 2 = 0, so this condition matches on 2024-01-27
# The divisor use to specify the period, the remainder use to specify the offset
# The offset is equal to num_days_since_ce % divisor
# The num_days_since_ce is the number of days since the Common Era, 0001-01-01 is the first day
# The offset of current day can be got by `maa remainder <divisor>`
# for 2024-01-27, num_days_since_ce is 738,912,
# the offset of 2024-01-27 is 738,912 % 2 = 0
# so this condition will be matched on 2024-01-27
{ type = "DayMod", divisor = 2, remainder = 0 },
{ type = "Time", start = "04:00:00", end = "12:00:00" },
]
}
params = { plan_index = 0 }
@@ -134,7 +136,7 @@ params = { plan_index = 1 }
# The third shift, 20:00:00 (first day) - 04:00:00 (second day)
[[tasks.variants]]
# Note: we must use Or condition here to properly handle the time across midnight
# Note, we must use Or condition here, otherwise the second day 00:00:00 - 04:00:00 will not be matched
condition = {
type = "Or",
conditions = [
@@ -190,9 +192,9 @@ condition = {
params = { plan_index = 5 }
```
With the default strategy, if multiple variants are matched, only the first one will be used. If no condition is given, the variant will always be matched. So you can put a variant without condition at the end as a default case.
With the default strategy, if multiple variants are matched, only the first one will be used. If the condition is not given, the variant will always be matched. So you can put a variant without condition at the end of variants.
The strategy for matching variants can be changed with the `strategy` field:
The strategy of matching variants can be changed by `strategy` field:
```toml
[[tasks]]
@@ -224,11 +226,11 @@ params = { stage = "SL-8" }
condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" }
```
This example will yield the same stage selection as the previous one, but will additionally use expiring medicine on Sunday night.
With the `merge` strategy, if multiple variants are matched, the parameters of all matched variants will be merged. If multiple variants have the same parameter keys, the later ones will override earlier ones.
The outcome stage of this example should be identical to the previous one, but expiring medicine will be used on Sunday night additionally.
With the `merge` strategy, if multiple variants are matched, the parameters of all matched variants will be merged. If multiple variants have the same parameters, the last one will be used.
If no variant is matched, the task will not be executed,
which is useful when you want to only run a task under certain conditions:
which is useful when you want to only run a task in some conditions:
```toml
# Mall after 18:00
@@ -239,9 +241,9 @@ type = "Mall"
condition = { type = "Time", start = "18:00:00" }
```
### User Input
### User input
For some tasks, you might want to input values at runtime rather than hardcoding them in the task file. You can set parameters to `Input` or `Select` type:
In some cases, you may want to input some value at runtime, instead of hard code it in the task file. Such as the stage to fight, the item to buy, etc. You can specify the value as `Input` or `Select` type:
```toml
[[tasks]]
@@ -259,9 +261,9 @@ alternatives = [
"SL-7", # will be displayed as "1. SL-7"
{ value = "SL-8", desc = "Manganese Ore" } # will be displayed as "2. SL-8 (Manganese Ore)"
]
default_index = 1 # the index of default value, start from 1, if not given, empty input will re-prompt
default_index = 1 # the index of default value, start from 1, if not given, empty value will be re-prompt
description = "a stage to fight in summer event" # description of the input, optional
allow_custom = true # whether to allow custom value input, default is false; if true, non-integer inputs are treated as custom values
allow_custom = true # whether allow input custom value, default to false, if allow, non-integer value will be treated as custom value
# Task without input
[[tasks.variants]]
@@ -271,29 +273,30 @@ params = { stage = "CE-6" }
# Input a stage to fight
[[tasks.variants]]
# Set the stage to an `Input` type with default value and description
# Set the stage to a `Input` type with default value and description
[tasks.variants.params.stage]
default = "1-7" # default value of stage, optional (if not given, empty input will re-prompt)
default = "1-7" # default value of stage, optional (if not given, user can input empty value to re-prompt)
description = "a stage to fight" # description of the input, optional
# query the medicine to use only when stage is 1-7
[tasks.variants.params.medicine]
# a parameter can be conditional based on other parameter values
# the condition uses a table where keys are other parameter names and values are the expected values
# this condition means "only prompt for medicine when stage is 1-7"
# a parameter can be optional with `optional` field
# if the condition is not matched, the parameter will be ignored
# the `condition` field can be used to specify the condition of the parameter
# where the condition can be a table, whose keys are name of other parameters and values are the expected value
conditions = { stage = "1-7" }
default = 1000
description = "medicine to use"
```
For an `Input` type, a prompt will be shown to ask the user to input a value. If a default value is given, it will be used when the user inputs an empty value; otherwise, it will re-prompt.
For a `Select` type, a prompt will be shown to ask the user to input an index or custom value (if `allow_custom` is `true`). If a default index is given, it will be used when the user inputs an empty value; otherwise, it will re-prompt.
For an `Input` type, a prompt will be shown to ask the user to input a value. If the default value is given, it will be used if the user inputs an empty value, otherwise, it will re-prompt.
For `Select` type, a prompt will be shown to ask the user to input an index or custom value (if `allow_custom` is `true`). If the default index is given, it will be used if the user inputs an empty value, otherwise, it will re-prompt.
The `--batch` option can be used to run tasks in batch mode, which will use default values for all inputs and error if no default value is given.
`--batch` option can be used to run tasks in batch mode, which will use the default value for all inputs and panic if no default value is given.
## MaaCore Related Configurations
## MaaCore related configurations
The MaaCore configuration files are called "Profiles" and located in the `$MAA_CONFIG_DIR/profiles` directory. Each file in this directory is a profile, with the default being `default.toml`. To use a different profile, specify it with the `-p` or `--profile` option.
The related configuration files of MaaCore is called "Profile" and located in `$MAA_CONFIG_DIR/profiles` directory. Each files in this directory is a profile, while the default profile is `default.toml`. If you want to use a profile other than the default one, you can specify it by `-p` or `--profile` option.
The currently available configurations are:
@@ -322,159 +325,152 @@ kill_adb_on_exit = false
### Connection
The `connection` section specifies how to connect to the game:
The `connection` section is used to specify how to connect to the game:
```toml
[connection]
adb_path = "adb" # path to adb executable, default is "adb" (uses PATH)
address = "emulator-5554" # device address like "emulator-5554" or "127.0.0.1:5555"
config = "General" # connection configuration, rarely needs changing
adb_path = "adb" # the path of adb executable, default to "adb", which means use adb in PATH
address = "emulator-5554" # the address of device, such as "emulator-5554" or "127.0.0.1:5555"
config = "General" # the config of maa, should not be changed most of time
```
`adb_path` is the path to the `adb` executable - you can set its absolute path or leave it empty to use it from PATH. Most emulators include `adb`, so you can use their built-in version without installing separately. `address` is the address used by `adb`. For emulators, use `127.0.0.1:[port]` - common emulator ports are listed in the [FAQ][emulator-ports]. If no address is specified, maa-cli tries to find a device with `adb devices`, using the first one found or defaulting to `emulator-5554` if none are found. `config` specifies platform/emulator configurations - defaults to `CompatPOSIXShell` on Linux, `CompatMac` on macOS, and `General` on other platforms. More options are in the resource folder's `config.json`.
`adb_path` is the path of `adb` executable, you can set it to the absolute path of `adb` or or leave it empty if it is in PATH. The `address` is the address of the device used by `adb`, like `emulator-5554` or `127.0.0.1:[port]`, the port of some common emulators can be found in the [MAA FAQ][emulator-ports]. If the `address` is absent, the cli will try to find the device automatically by `adb devices`, if there are multiple online devices, the first one will be used. If cli can not find any device, it will try to use the default address `emulator-5554`. The `config` is used to specify some configurations of the host and emulator, whose default value is `CompatMac` on macOS, `CompatPOSIXShell` on Linux and `General` on other platforms. More optional configs can be found in `config.json` in the resource directory.
For common emulators, you can use `preset` for predefined configurations:
For some common emulators, you can use `preset` to use predefined configurations:
```toml
[connection]
preset = "MuMuPro" # Use MuMu Pro emulator preset
adb_path = "/path/to/adb" # Override the preset's adb path if needed (optional)
address = "127.0.0.1:7777" # Override the preset's address if needed (optional)
preset = "MuMuPro"
adb_path = "/path/to/other/adb" # override predefined adb executable path
address = "127.0.0.1:7777" # override the predefined address
```
Currently only `MuMuPro` preset is available. Issues and PRs for more presets are welcome.
Currently, there is only one preset `MuMuPro` for emulators. Issue and PR are welcome for the new preset.
#### Special Presets
There are two special presets: `PlayCover (macOS)` and `Waydroid (Linux)`
- `PlayCover` is for connecting to iOS apps running natively on macOS through PlayCover. In this case, `adb_path` is ignored and `address` is the address of `PlayTools`. See [PlayCover documentation][playcover-doc] for details.
- `Waydroid` is for connecting to Android apps running natively on Linux through Waydroid. `adb_path` is still required. See [Waydroid documentation][waydroid-doc] for details.
There is a special preset `PlayCover`, used for the iOS app running on macOS by PlayCover. In this case, `adb_path` is ignored and `address` is used to specify the address of `MaaTools` set in `PlayCover`, more details can be found in the [PlayCover documentation][playcover-doc].
### Resource
The `resource` section specifies which resources MaaCore should load:
The `resource` section is used to specify the resource to use:
```toml
[resource]
global_resource = "YoStarEN" # Non-Chinese resources
platform_diff_resource = "iOS" # Non-Android resources
user_resource = true # Whether to load user-defined resources
global_resource = "YoStarEN" # the global resource to use
platform_diff_resource = "iOS" # the platform diff resource to use
user_resource = true # whether use user resource
```
When using a non-Simplified Chinese game client, set `global_resource` to load non-Chinese resources. When using an iOS client, set `platform_diff_resource` to `iOS`. Both are optional - leave empty to not load these resources. These are also auto-set based on your `startup` task's `client_type` and when using `PlayTools` connection. To load user-defined resources, set `user_resource` to `true`, which loads resources from `$MAA_CONFIG_DIR/resource`.
When your game is not in Simplified Chinese, you should set `global_resource` to non-Chinese resource. If you connect to the game with `PlayCover`, you should set `platform_diff_resource` to `iOS`.
Leave those two fields empty if you don't want to use global resource or platform diff resource. Besides, those two fields will also be set up automatically by maa-cli based on your task and connection type.
Lastly, if you want to use user resources, you should set `user_resource` to `true`. When `user_resource` is `true`, maa-cli will try to find user resources in `$MAA_CONFIG_DIR/resource` directory.
### Static options
The `static_options` section configures MaaCore static options:
The `static_options` section is used to configure MAA static options:
```toml
[static_options]
cpu_ocr = false # Whether to use CPU OCR (enabled by default)
gpu_ocr = 1 # GPU ID for GPU OCR; leave empty to use CPU OCR
cpu_ocr = false # whether use CPU OCR, CPU OCR is enabled by default
gpu_ocr = 1 # the ID of your GPU, leave it to empty if you don't want to use GPU OCR
```
### Instance options
The `instance_options` section configures MaaCore instance options:
The `instance_options` section is used to configure MAA instance options:
```toml
[instance_options]
touch_mode = "ADB" # Touch mode: "ADB", "MiniTouch", "MaaTouch", or "MacPlayTools"
deployment_with_pause = false # Whether to pause game during deployment
adb_lite_enabled = false # Whether to use adb-lite
kill_adb_on_exit = false # Whether to kill adb on exit
touch_mode = "ADB" # touch mode to use, can be "ADB", "MiniTouch", "MaaTouch" or "MacPlayTools" (only for PlayCover)
deployment_with_pause = false # whether pause the game when deployment
adb_lite_enabled = false # whether use adb-lite
kill_adb_on_exit = false # whether kill adb when exit
```
Note: When using `PlayTools` connection, `touch_mode` is forced to `MacPlayTools` regardless of setting.
Note: If you connect to the game with `PlayCover`, the `touch_mode` will be ignored and `MacPlayTools` will be used.
## CLI Related Configurations
## CLI related configurations
CLI-related configurations should be in `$MAA_CONFIG_DIR/cli.toml`. Current configurations include:
The CLI related configurations should be located in `$MAA_CONFIG_DIR/cli.toml`. Currently, it only contains one section: `core`:
```toml
# MaaCore install and update configurations
# MaaCore install and update configurations
[core]
channel = "Stable" # Update channel: "Alpha", "Beta", or "Stable" (default)
test_time = 0 # Time to test mirror speeds in seconds; 0 to skip, default is 3
# API URL to query latest MaaCore version; leave empty for default
api_url = "https://github.com/MaaAssistantArknights/MaaRelease/raw/main/MaaAssistantArknights/api/version/"
# Component installation config (not recommended to change)
channel = "Stable" # update channel, can be "Stable", "Beta" or "Alpha"
test_time = 0 # the time to test download mirrors in seconds, 0 to skip
# the url to query the latest version of MaaCore, leave it to empty to use default url
apit_url = "https://github.com/MaaAssistantArknights/maa-cli/raw/version/"
[core.components]
library = true # Whether to install MaaCore library
resource = true # Whether to install MaaCore resources
library = true # whether install MaaCore library
resource = false # whether install resource resource
# CLI update configurations
[cli]
channel = "Stable" # Update channel: "Alpha", "Beta", or "Stable" (default)
# API URL to query latest maa-cli version; leave empty for default
channel = "Stable" # update channel, can be "Stable", "Beta" or "Alpha"
# the url to query the latest version of maa-cli, leave it to empty to use default url
api_url = "https://github.com/MaaAssistantArknights/maa-cli/raw/version/"
# URL to download prebuilt binaries; leave empty for default
# the url to download prebuilt binary, leave it to empty to use default url
download_url = "https://github.com/MaaAssistantArknights/maa-cli/releases/download/"
[cli.components]
binary = true # Whether to install maa-cli binary
binary = true # whether install maa-cli binary
# Resource hot update configurations
# hot update resource configurations
[resource]
auto_update = true # Whether to auto-update resources before running tasks
warn_on_update_failure = true # Whether to warn instead of error on update failure
backend = "libgit2" # Hot update backend: "git" or "libgit2"
auto_update = true # whether auto update resource before running task
warn_on_update_failure = true # Whether to warn on update failure instead of panic
backend = "libgit2" # the backend of resource, can be "libgit2" or "git"
# Remote repository configuration
# the remote of resource
[resource.remote]
branch = "main" # Branch of remote repository
# Repository URL; leave empty for default
# GitHub repositories support both HTTPS and SSH; HTTPS recommended
url = "https://github.com/MaaAssistantArknights/MaaResource.git"
# url = "git@github.com:MaaAssistantArknights/MaaResource.git"
# If using SSH, you need to provide authentication:
# 1. Using ssh-agent (recommended)
# use_ssh_agent = true # Use ssh-agent for authentication
# 2. Using SSH key file
ssh_key = "~/.ssh/id_ed25519" # Path to SSH key
# If your key is password-protected:
passphrase = "password" # Passphrase for SSH key
# Storing plaintext passwords is insecure. Alternatives:
# 1. Set passphrase to true to be prompted each time
branch = "main" # Branch of remote resource repository
# URL of remote resource repository, leave it empty to use the default URL
url = "git@github.com:MaaAssistantArknights/MaaResource.git"
# If you want to use ssh, a certificate is needed which can be "ssh-agent" or "ssh-key"
# To use ssh-agent, set `use_ssh_agent` to true, and leave `ssh_key` and `passphrase` empty
# use_ssh_agent = true # Use ssh-agent to authenticate
# To use ssh-key, set `ssh_key` to path of ssh key,
ssh_key = "~/.ssh/id_ed25519" # Path of ssh key
# A Passphrase is needed if the ssh key is encrypted
passphrase = "password" # Passphrase of ssh key
# Store plain text password in configuration file is unsafe, so there are some ways to avoid it
# 1. set `passphrase` to true, then maa-cli will prompt you to input passphrase each time
# passphrase = true
# 2. Use an environment variable
# 2. set `passphrase` to a environment variable, then maa-cli will use the environment variable as passphrase
# passphrase = { env = "MAA_SSH_PASSPHRASE" }
# 3. Use a command output (useful with password managers)
# 3. set `passphrase` to a command, then maa-cli will execute the command to get passphrase
# which is useful when you use a password manager to manage your passphrase
# passphrase = { cmd = ["pass", "show", "ssh/id_ed25519"] }
```
**NOTE**:
- The `Alpha` channel for MaaCore is only available on Windows
- Hot update resources require the basic resources installed with MaaCore
- Using the `git` backend requires the `git` command to be available
- SSH authentication requires either `ssh_key` configuration or `ssh-agent`
- The `resource.remote.url` only affects first installation; to change it later, modify it manually or delete and reinstall resources. Get the repository location with `maa dir hot-update`.
- The `Alpha` channel of MaaCore is only available on Windows;
- The hot update resource can not work separately, it should be used with basic resources installed with MaaCore;
- If you want to use `git` backend, `git` command is required;
- If you want to fetch resources with ssh, the `ssh_key` is required;
- The `resource.remote.url` only affects first-time installation, it will be ignored when updating resource. If you want to change the remote URL, you should change it manually or delete the resource directory and reinstall the resources. The directory of the repository can be located by `maa dir hot-update`.
## Example Configuration Files
## Example of config file
- [Example configurations][example-config]
- [Maintainer's configuration][wangl-cc-dotfiles]
- [Example configuration][example-config];
- [Configuration used by maintainer][wangl-cc-dotfiles].
## JSON Schema
## JSON schema
JSON schemas for configuration files are in the [`schemas` directory][schema-dir]:
The JSON schema of configuration files can be found at [`schemas` directory][schema-dir]:
- Task configuration schema: [`task.schema.json`][task-schema]
- MaaCore configuration schema: [`asst.schema.json`][asst-schema]
- CLI configuration schema: [`cli.schema.json`][cli-schema]
- The schema of the task configuration is [`task.schema.json`][task-schema];
- the schema of the MaaCore configuration file is [`asst.schema.json`][asst-schema];
- the schema of the CLI configuration file is [`cli.schema.json`][cli-schema].
With these schemas, you can get auto-completion and validation in supported editors with plugins.
With the help of JSON schema, you can get auto-completion and validation in some editors with plugins.
[task-types]: ../../protocol/integration.md#list-of-task-types
[emulator-ports]: ../../manual/connection.md#obtain-port-number
[playcover-doc]: ../../manual/device/macos.md#%E2%9C%85-playcover-the-software-runs-most-fluently-for-its-nativity-%F0%9F%9A%80
[waydroid-doc]: ../../manual/device/linux.md#✅-waydroid
[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa
[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/
[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/task.schema.json
[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/asst.schema.json

2
docs/en-us/manual/cli/faq.md
View File

@@ -7,7 +7,7 @@ icon: ph:question-fill
## 1. How to use `$HOME/.config/maa` as the configuration directory on macOS?
Due to the Rust library [Directories](https://github.com/dirs-dev/directories-rs/) using Apple-style directories on macOS by default, maa-cli also uses Apple-style configuration directories by default. However, XDG-style directories are more suitable for command-line programs. If you want to use XDG-style directories, you can set the `XDG_CONFIG_HOME` environment variable, such as `export XDG_CONFIG_HOME="$HOME/.config"`, which will make maa-cli use XDG-style configuration directories. If you want to use XDG-style configuration directories but don't want to set environment variables, you can use the following command to create a symbolic link:
Due to the limitation of [Directories](https://github.com/dirs-dev/directories-rs/), maa-cli uses the Apple-style configuration directory on macOS by default. However, the XDG-style configuration directory is more suitable for command-line programs. If you want to use the XDG style configuration directory, you can set the `XDG_CONFIG_HOME` environment variable, such as `export XDG_CONFIG_HOME="$HOME/.config"`, this will make maa-cli use the XDG style configuration directory. Or you can use the below command to create a symbolic link:
```bash
mkdir -p "$HOME/.config/maa"

10
docs/en-us/manual/cli/install.md
View File

@@ -47,7 +47,7 @@ Homebrew users can install maa-cli via the unofficial [tap](https://github.com/M
nix run github:Cryolitia/nur-packages#maa-cli-nightly
```
Stable is packaged in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-cli/package.nix), using the nixpkgs Rust toolchain; Nightly is in [NUR](https://github.com/Cryolitia/nur-packages/blob/master/pkgs/maa-assistant-arknights/maa-cli.nix), using the Beta Channel Rust toolchain, automatically updated and built daily by GitHub Actions.
Stable is the maa-cli packaged in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/ma/maa-cli/package.nix), using the nixpkgs's Rust toolchain; Nightly is in [NUR](https://github.com/Cryolitia/nur-packages/blob/master/pkgs/maa-assistant-arknights/maa-cli.nix), uses the Beta Channel of Rust toolchain, automatically updates and builds for verification by Github Action daily.
- Users using Homebrew on Linux please refer to the macOS installation method above.
@@ -96,14 +96,6 @@ maa-cli only provides an interface for MaaCore, it needs MaaCore and resources t
maa install
```
For Windows platform users, before running the `maa install` command, please run the following command as administrator in Command Prompt or PowerShell to install the required VC++ toolset:
- Windows:
```bat
winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force
```
For users who installed via package managers, MaaCore can also be installed via package managers:
- Homebrew：

82
docs/en-us/manual/cli/usage.md
View File

@@ -5,98 +5,96 @@ icon: material-symbols:summarize
# Usage
maa-cli's main functionality is to automate Arknights game tasks by calling MaaCore. Additionally, for convenience, maa-cli also provides functions to manage MaaCore.
maa-cli is a command-line interface for MaaCore that automates tasks in the game Arknights. Additionally, maa-cli can manage MaaCore.
## Manage MaaCore
maa-cli can install and update MaaCore and resources by running the following commands:
maa-cli can install and update MaaCore and resources, just run the following commands:
```bash
maa install # Install MaaCore and resources
maa update # Update MaaCore and resources
```
## Update maa-cli Itself
## Update maa-cli itself
maa-cli can update itself by running the following command:
maa-cli can update itself, just run the following command:
```bash
maa self update
```
**Note**: Users who installed maa-cli via a package manager should use the package manager to update maa-cli. This command will not work for those users.
**Note**: Users who install maa-cli via a package manager should use the package manager to update maa-cli, this command is invalid for these users.
## Initialize Configuration
Once MaaCore is installed, you can typically run tasks directly without additional configuration. However, the default configuration may not be suitable for all users, so you can initialize the configuration with:
Once MaaCore is installed, you can run tasks directly without additional configuration. The default configuration may not be suitable for all users. Therefore, you can initialize the configuration by running the following command:
```bash
maa init
```
With this command, you can interactively configure [MaaCore-related settings][config-core].
With this command, you can configure [the relevant configurations of MaaCore][config-core] interactively.
## Run Tasks
After installing and configuring MaaCore, you can run tasks. maa-cli supports two types of tasks: predefined tasks and custom tasks.
### Predefined Tasks
### Predefined tasks
For common tasks, maa-cli provides several predefined options:
- `maa startup [client]`: start the game client and enter the main screen, the `client` is the client type of game, leave it empty to don't start the game.
- `maa closedown [client]`: close the game client, the `client` is the client type of game, default is `Official`.
- `maa fight [stage]`: run a "fight" task, the `stage` is the stage to fight, like `1-7`, `CE-6`, etc.; if not given, the user will be prompted to input one.
- `maa copilot <maa_uri>...`: run a "copilot" task, the `maa_uri` is the URI of a copilot task, multiple URIs will be executed in sequence, `maa_uri` can be `maa://1234` or local file path `./1234.json`.
- `maa sscopilot <maa_uri>`: run a "sscopilot" task, the `maa_uri` is the URI of a sscopilot task.
- `maa roguelike [theme]`: run a "roguelike" task, the `theme` is the theme of roguelike, and available themes are `Phantom`, `Mizuki`, `Sami` and `Sarkaz`.
- `maa reclamation [theme]`: run a "reclamation" task, the `theme` is the theme of reclamation, and available themes are `Tales`.
- `maa startup [client]`: Start the game and enter the main interface. `[client]` is the client type; leave empty to not start any game client.
- `maa closedown [client]`: Close the game client. `[client]` is the client type, defaulting to `Official`.
- `maa fight [stage]`: Run a combat task. `[stage]` is the stage name like `1-7`; leave empty to select the last or current stage.
- `maa copilot <maa_uri>...`: Auto-run copilot tasks. `<maa_uri>` is the task URI, multiple URIs will execute in sequence. `maa_uri` can be `maa://1234` or a local file path like `./1234.json`.
- `maa sscopilot <maa_uri>`: Auto-run Stationary Security Service tasks. `<maa_uri>` is the task URI.
- `maa roguelike <theme>`: Auto-run Integrated Strategy. `<theme>` is the theme, with options including `Phantom`, `Mizuki`, `Sami`, `Sarkaz`, and `JieGarden`.
- `maa reclamation <theme>`: Auto-run Reclamation Algorithm. `<theme>` is the theme, currently only `Tales` is available.
The above tasks accept some parameters, you can view the specific parameters by `maa <task> --help`.
These tasks accept various parameters. You can view the specific parameters with `maa <task> --help`.
For example, if you want to open the game, use 3 sanity potions to farm BB-7, and then close the game, you can run:
For example, if you want to open the game, use 3 sanity medicines to farm BB-7, and then close the game, you can run the following command:
```bash
maa startup Official && maa fight BB-7 -m 3 && maa closedown
maa startup YoStarEN && maa fight BB-7 -m 3 && maa closedown
```
### Custom Tasks
Due to MAA's support for numerous tasks, maa-cli cannot provide predefined options for everything. Additionally, you may need to run multiple tasks as in the example above. To address this, maa-cli offers custom task functionality. Custom tasks can combine different tasks, providing finer control over parameters and execution order. They also support conditional execution based on specific criteria, automating your daily routines. Custom tasks are defined via configuration files—see the [Custom Task Documentation][custom-task] for details on location and format. After creating a configuration file, run your custom task with `maa run <task>`, where `<task>` is the filename without extension.
Due to the multitude of tasks supported by MAA, maa-cli cannot provide predefined options for all tasks. Additionally, you may need to run multiple tasks as shown in the example above. To address this issue, maa-cli offers custom task functionality. Custom tasks allow for the combination of different tasks and provide finer control over the parameters of each task as well as the execution order. Furthermore, custom tasks support conditional statements, enabling you to decide whether to execute a task based on certain conditions or to execute a task with specific parameters. This can be used to automate your daily tasks. A custom task is defined in a configuration file. The location and format of the configuration file are described in the [Custom Task Document][custom-task]. After defining the configuration file, you can run the custom task by `maa run <task>`, where `<task>` is the name of the custom task, excluding the extension.
### Task Summary
Both predefined and custom tasks output summary information upon completion, including each subtask's runtime (start time, end time, duration). For certain tasks, result summaries include:
maa-cli will output a summary of the task after the task is terminated, including the running time of each subtask (start time, end time, running time). For some tasks, it will also output a summary of the task results:
- `fight` task: Stage name, number of runs, sanity potions used, and drop statistics
- `infrast`: Operators assigned to each facility, including product types for factories and trading posts
- `recruit`: Tags, star ratings, and status for each recruitment, plus total recruitment count
- `roguelike`: Exploration count, investment count
- `fight` task: stage name, times, sanity cost, and drop statistics;
- `infrast`: operators stationed in each facility, for the factory and trading post, it also includes the type of product;
- `recruit`: tags, star ratings, and status of each recruitment, as well as the total number of recruitments;
- `roguelike`: exploration times, investment times.
If you don't want task summaries, disable them with the `--no-summary` parameter.
If you don't want the task summary, you can turn it off by `--no-summary`.
### Task Logging
### Loggings
maa-cli outputs logs with the following levels (low to high): `Error`, `Warn`, `Info`, `Debug`, and `Trace`. The default level is `Warn`. Set the log level via the `MAA_LOG` environment variable (e.g., `MAA_LOG=debug`) or use `-v` to increase and `-q` to decrease the level.
maa-cli will output logs, the log output levels from low to high are `Error`, `Warn`, `Info`, `Debug`, and `Trace`. The default log output level is `Warn`. The log level can be set by the `MAA_LOG` environment variable, for example, `MAA_LOG=debug`. You can also increase or decrease the log output level by `-v` or `-q`.
By default, logs go to standard error (stderr). The `--log-file` option can redirect logs to a file at `$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log`, where `$(maa dir log)` is the log directory obtainable via `maa dir log`. You can also specify a custom log path with `--log-file=path/to/log`.
maa-cli will output logs to stderr by default. The `--log-file` option can output logs to a file, the logs are saved in `$(maa dir log)/YYYY/MM/DD/HH:MM:SS.log`, where `$(maa dir log)` is the log directory, you can get it by `maa dir log`. You can also specify the log file path by `--log-file=path/to/log`.
All logs normally include a timestamp and level prefix. The `MAA_LOG_PREFIX` environment variable controls this behavior: `Always` always includes prefixes, `Auto` includes prefixes in log files but not in stderr output, and `Never` omits prefixes even in log files.
By default, all output logs will include a timestamp and a log-level prefix. You can change this behavior by the `MAA_LOG_PREFIX` environment variable. When set to `Always`, the prefix will always be included, when set to `Auto`, the prefix will be included when writing to the log file, and not included when writing to stderr, and when set to `Never`, the prefix will not be included even when writing to the log file.
### Other Subcommands
### Other subcommands
Besides the above commands, maa-cli provides additional subcommands:
Except for the above subcommands, maa-cli also provides other subcommands:
- `maa list`: List all available tasks
- `maa dir <dir>`: Get a specific directory path, such as `maa dir config` for the configuration directory
- `maa version`: Get version information for `maa-cli` and `MaaCore`
- `maa convert <input> [output]`: Convert between `JSON`, `YAML`, or `TOML` format files
- `maa complete <shell>`: Generate auto-completion scripts
- `maa activity [client]`: Get current in-game activity information, with `[client]` defaulting to `Official`
- `maa cleanup`: Clean `maa-cli` and `MaaCore` caches
- `maa import <file> [-t <type>]`: Import a configuration file, with `-t` specifying the type (e.g., `cli`, `profile`, `infrast`)
- `maa list`: list all available tasks;
- `maa dir <dir>`: get the path of a specific directory, for example, `maa dir config` can be used to get the path of the configuration directory;
- `maa version`: get the version information of `maa-cli` and `MaaCore`;
- `maa convert <input> [output]`: convert a file in `JSON`, `YAML`, or `TOML` format to another format;
- `maa complete <shell>`: generate an auto-completion script;
- `maa activity [client]`: get the current activity information of the game, the `client` is the client type, default is `Official`.
- `maa cleanup`: clean up the cache of `maa-cli` and `MaaCore`.
- `maa import <file> [-t <type>]`: import a configuration file, the `file` is the path of the configuration file. The `-t` option can specify the type of the configuration file, such as `cli`, `profile`, `infrast`, etc.
For more command information, use `maa help`. For specific command details, use `maa help <command>`.
More command usage can be viewed by `maa help`, and the usage of specific commands can be viewed by `maa help <command>`.
[config-core]: config.md#maacore-related-configurations
[custom-task]: config.md#custom-tasks

2
docs/ja-jp/manual/cli/config.md
View File

@@ -468,7 +468,7 @@ passphrase = "password" # ssh 密钥的密码
[emulator-ports]: ../../manual/connection.md#获取端口号
[playcover-doc]: ../../manual/device/macos.md#✅-playcover-原生运行最流畅-🚀
[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa
[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/
[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/task.schema.json
[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/asst.schema.json

2
docs/ja-jp/manual/cli/usage.md
View File

@@ -53,7 +53,7 @@ maa init
- `maa fight [stage]`: 运行战斗任务，`[stage]` 是关卡名称，例如 `1-7`；留空选择上次或者当前关卡。
- `maa copilot <maa_uri>...`: 自动抄作业，其中 `<maa_uri>` 是作业的 URI，多个 URI 会依次执行，`maa_uri` 可以是 `maa://1234` 或者 本地文件路径 `./1234.json`。
- `maa sscopilot <maa_uri>`: 自动保全派驻，其中 `<maa_uri>` 是保全派驻作业的 URI。
- `maa roguelike <theme>`: 自动集成战略，`<theme>` 是集成战略的主题，可选值为 `Phantom`，`Mizuki`，`Sami`， `Sarkaz` 以及 `JieGarden`。
- `maa roguelike <theme>`: 自动集成战略，`<theme>` 是集成战略的主题，可选值为 `Phantom`，`Mizuki`，`Sami` 以及 `Sarkaz`。
- `maa reclamation <theme>`: 自动生息演算，`<theme>` 是生息演算的主题，目前仅 `Tales` 主题可用。
上述任务接受一些参数，你可以通过 `maa <task> --help` 来查看具体的参数。

2
docs/ko-kr/manual/cli/config.md
View File

@@ -451,7 +451,7 @@ passphrase = "password" # ssh 키의 암호
[emulator-ports]: ../../manual/connection.md#포트-번호-입력
[playcover-doc]: ../../manual/device/macos.md#✅-playcover-제일-부드럽습니다-🚀
[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa
[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/
[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/task.schema.json
[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/asst.schema.json

2
docs/ko-kr/manual/cli/usage.md
View File

@@ -49,7 +49,7 @@ MaaCore의 설치 및 구성을 완료하면 작업을 실행할 준비가 된
- `maa fight [stage]`: 전투 작업을 실행합니다. `[stage]`는 스테이지 이름이며, 예를 들어 `1-7`입니다. 생략하면 이전 또는 현재 스테이지를 선택합니다.
- `maa copilot <maa_uri>...`: 자동 전투 작업을 실행합니다. `<maa_uri>`는 작업의 URI이며, 여러 URI는 순차적으로 실행됩니다. `maa_uri`는 `maa://1234` 또는 로컬 파일 경로 `./1234.json`일 수 있습니다.
- `maa sscopilot <maa_uri>`: 자동 보안 파견을 실행합니다. `<maa_uri>`는 보안 파견 작업의 URI입니다.
- `maa roguelike <theme>`: 자동 통합 전략을 실행합니다. `<theme>`는 통합 전략의 주제이며, 선택 가능한 값은 `Phantom`, `Mizuki`, `Sami`, `Sarkaz`, `JieGarden`입니다.
- `maa roguelike <theme>`: 자동 통합 전략을 실행합니다. `<theme>`는 통합 전략의 주제이며, 선택 가능한 값은 `Phantom`, `Mizuki`, `Sami`, `Sarkaz`입니다.
- `maa reclamation <theme>`: 자동 생활 게임을 실행합니다. `<theme>`는 생활 게임의 주제이며, 현재 사용 가능한 값은 `Tales`입니다.
위 작업들은 몇 가지 매개변수를 받습니다. `maa <task> --help` 명령어를 통해 자세한 매개변수를 확인할 수 있습니다.

2
docs/zh-cn/manual/cli/config.md
View File

@@ -471,7 +471,7 @@ passphrase = "password" # ssh 密钥的密码
[playcover-doc]: ../../manual/device/macos.md#✅-playcover-原生运行最流畅-🚀
[waydroid-doc]: ../../manual/device/linux.md#✅-waydroid
[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa
[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/
[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/task.schema.json
[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/asst.schema.json

2
docs/zh-tw/manual/cli/config.md
View File

@@ -467,7 +467,7 @@ passphrase = "password" # ssh 密钥的密码
[emulator-ports]: ../../manual/connection.md#获取端口号
[playcover-doc]: ../../manual/device/macos.md#✅-playcover-原生运行最流畅-🚀
[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/config_examples
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa
[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/main/home/dot_config/maa
[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/
[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/task.schema.json
[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/crates/maa-cli/schemas/asst.schema.json

2
docs/zh-tw/manual/cli/usage.md
View File

@@ -53,7 +53,7 @@ maa init
- `maa fight [stage]`: 运行战斗任务，`[stage]` 是关卡名称，例如 `1-7`；留空选择上次或者当前关卡。
- `maa copilot <maa_uri>...`: 自动抄作业，其中 `<maa_uri>` 是作业的 URI，多个 URI 会依次执行，`maa_uri` 可以是 `maa://1234` 或者 本地文件路径 `./1234.json`。
- `maa sscopilot <maa_uri>`: 自动保全派驻，其中 `<maa_uri>` 是保全派驻作业的 URI。
- `maa roguelike <theme>`: 自动集成战略，`<theme>` 是集成战略的主题，可选值为 `Phantom`，`Mizuki`，`Sami`，`Sarkaz` 以及 `JieGarden`。
- `maa roguelike <theme>`: 自动集成战略，`<theme>` 是集成战略的主题，可选值为 `Phantom`，`Mizuki`，`Sami` 以及 `Sarkaz`。
- `maa reclamation <theme>`: 自动生息演算，`<theme>` 是生息演算的主题，目前仅 `Tales` 主题可用。
上述任务接受一些参数，你可以通过 `maa <task> --help` 来查看具体的参数。

2
src/maa-cli

Submodule src/maa-cli updated: c7bd77c920...f00ba6fc5a