diff --git a/docs/.vuepress/sidebar/en-us.ts b/docs/.vuepress/sidebar/en-us.ts index 5bc6997ae1..6c0f1f063a 100644 --- a/docs/.vuepress/sidebar/en-us.ts +++ b/docs/.vuepress/sidebar/en-us.ts @@ -49,6 +49,13 @@ export const enusSidebar = sidebar({ }, ], }, + { + text: "User Manual For CLI", + icon: "material-symbols:terminal", + prefix: "user_manual_for_cli/", + collapsible: true, + children: "structure", + } ], }, { diff --git a/docs/.vuepress/sidebar/zh-cn.ts b/docs/.vuepress/sidebar/zh-cn.ts index e9d8a86f41..ef4ea3aec8 100644 --- a/docs/.vuepress/sidebar/zh-cn.ts +++ b/docs/.vuepress/sidebar/zh-cn.ts @@ -38,7 +38,7 @@ export const zhcnSidebar = sidebar({ { text: "CLI使用指南", icon: "material-symbols:terminal", - prefix: "CLI使用指南/", + prefix: "user_manual_for_cli/", collapsible: true, children: "structure", }, diff --git a/docs/en-us/1.6-USER_GUIDE_FOR_CLI.md b/docs/en-us/1.6-USER_GUIDE_FOR_CLI.md deleted file mode 100644 index bcee85b940..0000000000 --- a/docs/en-us/1.6-USER_GUIDE_FOR_CLI.md +++ /dev/null @@ -1,357 +0,0 @@ ---- -icon: material-symbols:terminal ---- -# User Guide for CLI - -## Feature - -- Define tasks by TOML, YAML or JSON file, then run it by `maa run `; -- Install and update `MaaCore` and resources with `maa install` and `maa update`; -- Update self with `maa self update`; - -## Installation - -### Appimage - -The CLI is the default interface of MAA on Linux. You can use the CLI directly by downloading the latest [Appimage](https://github.com/MaaAssistantArknights/MaaAssistantArknights/releases/latest). - -### Package manager - -#### macOS - -Install with [Homebrew](https://brew.sh/): - -```bash -brew install MaaAssistantArknights/tap/maa-cli -``` - -#### Linux - -- Arch Linux users can install [AUR package](https://aur.archlinux.org/packages/maa-cli/): - - ```bash - yay -S maa-cli - ``` - -- Nix users can run directly: - - ```bash - # Stable - nix run nixpkgs#maa-cli - ``` - - ```bash - # Nightly - nix run github:Cryolitia/nur-packages#maa-cli-nightly - ``` - - Stable is the `maa-cli` that is 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), it uses the Beta Channel of Rust toolchain, automatically updates and builds for verification by Github Action daily. - -- For Linux Brew users, you can install with [Linux Brew](https://docs.brew.sh/Homebrew-on-Linux): - - ```bash - brew install MaaAssistantArknights/tap/maa-cli - ``` - -### Prebuilt binary - -You can install CLI by download prebuilt binary from -[`maa-cli` release page](https://github.com/MaaAssistantArknights/maa-cli/releases/latest) and extract it to your favorite location. The filename for different platform is: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Operation SystemArchitectureFilename
Linuxx86_64maa_cli-x86_64-unknown-linux-gnu.tar.gz
aarch64maa_cli-aarch64-unknown-linux-gnu.tar.gz
macOSx86_64 - maa_cli-universal-apple-darwin.zip -
aaarch64
Windowsx86_64maa_cli-x86_64-pc-windows-msvc.zip
- -### Build from source - -You can also build from source by yourself with `cargo`: - -```bash -cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked -``` - -### Dependencies - -#### MaaCore - -`maa-cli` only provides a interface for MaaCore, it needs `MaaCore` and resources to run tasks, which can be installed by `maa install`: - -```bash -maa install -``` - -## Usage - -### Commands - -The main feature of `maa-cli` is to run tasks, you can run a task by `maa run `. Here `` is the name of a task, you can list all available tasks by `maa list`. - -More details can be found by `maa help`. - -## Configurations - -### Configuration directory - -All configurations of `maa-cli` is located in a specific configuration directory, which can be get by `maa dir config`. -The configuration directory can be changed by environment variable `MAA_CONFIG_DIR`. In below examples, we will use `$MAA_CONFIG_DIR` to represent the configuration directory. - -All configuration files can be written in TOML, YAML or JSON format. In below examples, we will use TOML format and `.toml` as file extension. But you can mix these three formats as long as the file extension is correct. - -### Define tasks - -A `maa-cli` task should be defined in a single file, which should be located in `$MAA_CONFIG_DIR/tasks` directory. - -#### Basic structure - -A `maa-cli` task is a sequence of `MAA` tasks, each `MAA` task is defined by `type` and `params` fields: - -```toml -[[tasks]] -type = "StartUp" # the type of maa task -params = { client_type = "Official", start_game_enabled = true } # the params of given task -``` - -See documentation of [MAA](https://maa.plus/docs/en-us/3.1-INTEGRATION.html#asstappendtask) for all available task types and params. - -#### Task variants and conditions - -In some case, you may want to run a task with different params in different conditions. You can define multiple variants for a task, and use `condition` field to determine whether the variant should be used. For example, you may want to use different infrast plan in different time period of a day: - -```toml -[[tasks]] -type = "Infrast" - -[tasks.params] -mode = 10000 -facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] -dorm_trust_enabled = true -filename = "normal.json" # the filename of custom infrast plan - -# use plan 1 before 12:00:00, use plan 2 between 12:00:00 and 18:00:00, use plan 0 after 18:00:00 -[[tasks.variants]] -condition = { type = "Time", end = "12:00:00" } # if start is not defined, it will be 00:00:00 -params = { plan_index = 1 } - -[[tasks.variants]] -condition = { type = "Time", start = "12:00:00", end = "18:00:00" } -params = { plan_index = 2 } - -[[tasks.variants]] -condition = { type = "Time", start = "18:00:00" } # if end is not defined, it will be 23:59:59 -params = { plan_index = 0 } -``` - -The `condition` field is used to determine whether the variant should be used, -and the `params` field of matched variant will be merged into the params of the task. - -**Note**: If the `filename` field is a relative path, it will be relative to `$MAA_CONFIG_DIR/infrast`. Besides, the custom infrast plan file will not be read by `maa-cli` but `MaaCore`. So the format of the file must be `JSON` and 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 params of the task to use the correct infrast plan in the corresponding time period. This will ensure that the correct infrast plan is used in the appropriate time period. - -Besides of `Time` condition, there are also `DateTime`, `Weakday`, and `Combined` conditions. `DateTime` condition is used to specify a specific datetime period, `Weekday` condition is used to specify some days in a week, `Combined` condition is used to specify a combination of multiple conditions. - -```toml -[[tasks]] -type = "Fight" - -# fight SL-8 on summer event -[[tasks.variants]] -params = { stage = "SL-8" } -condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } -# fight CE-6 on Tue, Thu, Sat if not on summer event -[[tasks.variants]] -condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } -params = { stage = "CE-6" } -# fight 1-7 otherwise -[[tasks.variants]] -params = { stage = "1-7" } -``` - -With default strategy, if multiple variants are matched, only the first one will be used. And 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 of matching variants can be changed by `strategy` field: - -```toml -[[tasks]] -type = "Fight" -strategy = "merge" # or "first" (default) - -# use all expiring medicine on Sunday night -[[tasks.variants]] -params = { expiring_medicine = 1000 } -[tasks.variants.condition] -type = "Combined" -conditions = [ - { type = "Time", start = "18:00:00" }, - { type = "Weekday", weekdays = ["Sun"] }, -] - -# fight 1-7 by default -[[tasks.variants]] -params = { stage = "1-7" } - -# fight CE-6 on Tue, Thu, Sat if not on summer event -[[tasks.variants]] -condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } -params = { stage = "CE-6" } - -# fight SL-8 on summer event -[[tasks.variants]] -params = { stage = "SL-8" } -condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } -``` - -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 params of all matched variants will be merged. If multiple variants have the same param, 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 in some conditions: - -```toml -# Mall after 18:00 -[[tasks]] -type = "Mall" - -[[tasks.variants]] -condition = { type = "Time", start = "18:00:00" } -``` - -#### User input - -In some case, 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]] -type = "Fight" - -# Select a stage to fight -[[tasks.variants]] -condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } - -# Set the stage to a `Select` type with alternatives and description -[tasks.variants.params.stage] -alternatives = ["SL-6", "SL-7", "SL-8"] # the alternatives of stage, at least one alternative should be given -description = "a stage to fight in summer event" # description of the input, optional - -# Task without input -[[tasks.variants]] -condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } -params = { stage = "CE-6" } - -# Input a stage to fight -[[tasks.variants]] - -# 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, user can input empty value to re-prompt) -description = "a stage to fight" # description of the input, optional -``` - -For `Input` type, a prompt will be shown to ask user to input a value. If the default value is given, it will be used if user input empty value, otherwise it will re-prompt. For `Select` type, a prompt will be shown to ask user to select a value from alternatives (by index). If user input is not a valid index, it will re-prompt. The promote and input can be disabled by `--batch` option, which is useful for running tasks in Schedule. - -### `MaaCore` related configurations - -The related configurations of `MaaCore` is located in `$MAA_CONFIG_DIR/asst.toml`. The current available configurations are: - -```toml -user_resource = true -resources = ["platform_diff/iOS"] - -[connection] -type = "ADB" -adb_path = "adb" -device = "emulator-5554" -config = "CompatMac" - -[static_options] -cpu_ocr = false -gpu_ocr = 1 - -[instance_options] -touch_mode = "MAATouch" -deployment_with_pause = false -adb_lite_enabled = false -kill_adb_on_exit = false -``` - -The feild `user_resource` is used to specify whether load user resource, which is a boolean value. If it is `true`, additional resources in `$MAA_CONFIG_DIR/resource` directory will be loaded at last (after all other resources). This is identical to the `--user-resource` command line option. See `maa help run` for more information. - -The `resources` field is used to specify additional resources, which is a list of resource directories (if relative path is given, it will be relative to `$(maa dir resource)/resource` directory): - -The `connection` section is used to specify how to connect to the game. Currently, there are two types of connection: `ADB` and `PlayTools`. - -If you use `ADB`, you should set `adb_path` and `device` fields: - -```toml -[connection] -type = "ADB" -adb_path = "adb" # the path of adb executable -device = "emulator-5554" # the serial of your android device -config = "General" # the config of maa -``` - -If you use `PlayTools`, you should set `address` which is the address of MaaTools set in PlayCover, more details can be found at -[here](https://maa.plus/docs/en-us/1.4-EMULATOR_SUPPORTS_FOR_MAC.html#✅-playcover-the-software-runs-most-fluently-for-its-nativity-🚀): - -```toml -[connection] -type = "PlayTools" -address = "localhost:1717" # the address of MaaTools -config = "CompatMac" # the same as above -``` - -Both `ADB` and `PlayTools` share the `config` field, which is a parameter of `connect` function of maa.It's default value is `CompatMac` on macOS, `CompatPOSIXShell` on Linux and `General` on other platforms. More optional configs can be found in `config.json` in resource directory. - -The `instance_options` section is used to configure maa [instance options](https://maa.plus/docs/en-us/3.1-INTEGRATION.html#asstsetinstanceoption): - -```toml -[instance_options] -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: If you connect to the game with `PlayCover`, the `touch_mode` will be ignored and `MacPlayTools` will be used. - -### `maa-cli` related configurations - -The `maa-cli` related configurations should be located in `$MAA_CONFIG_DIR/cli.toml`. Currently, it only contains one section: `core`: - -```toml -[core] -channel = "beta" -[core.components] -resource = false -``` - -The `channel` field is used to specify the channel of `MaaCore` to install, which can be `stable`, `beta` or `alpha`. The components of `MaaCore` to install can be specified by `components` field, which is a table of boolean values. Currently, only `resource` component is supported. diff --git a/docs/en-us/user_manual_for_cli/cli-config.md b/docs/en-us/user_manual_for_cli/cli-config.md new file mode 100644 index 0000000000..e8c22b41ae --- /dev/null +++ b/docs/en-us/user_manual_for_cli/cli-config.md @@ -0,0 +1,461 @@ +--- +order: 4 +icon: material-symbols:settings +--- + +# Configuring maa-cli + +## Configuration Directory + +The maa-cli configuration files are located in a specific configuration directory, which you can get by running `maa dir config`. The configuration directory can also be changed by the environment variable `MAA_CONFIG_DIR`. In the following examples, we will use `$MAA_CONFIG_DIR` to represent the configuration directory. + +All configuration files can be in TOML, YAML, or JSON format. In the following examples, we will use the TOML format and use `.toml` as the file extension. But you can mix these three formats, as long as your file extension is correct. + +In addition, some tasks accept `filename` as a parameter. When the relative path is used, the relative path will be relative to the corresponding subdirectory of the configuration directory. For example, the custom infrastructure plan files should be relative to `$MAA_CONFIG_DIR/infrast`, while the copilot files of Stationary Security Service should be relative to `$MAA_CONFIG_DIR/ssscopilot`. + +## Custom Tasks + +A custom task is a separate file located in the `$MAA_CONFIG_DIR/tasks` directory. + +### Basic Structure + +A task file contains multiple subtasks, each of which is an MAA task, which contains the following options: + +```toml +[[tasks]] +name = "Start the game" # The name of the task, optional, defaults to the task type +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. + +### Task variants and conditions + +In some cases, you may want to run a task with different parameters in different conditions. You can define multiple variants for a task, and use the `condition` field to determine whether the variant should be used. For example, you may want to use a different infrastructure plan at different periods of the day: + +```toml +[[tasks]] +type = "Infrast" + +[tasks.params] +mode = 10000 +facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] +dorm_trust_enabled = true +filename = "normal.json" # the filename of custom infrast plan + +# use plan 0 from 18:00:00 to 04:00:00 of next day, use plan 1 before 12:00:00, use plan 2 after 12:00:00 +[[tasks.variants]] +condition = { type = "Time", start = "18:00:00", end = "04:00:00" } # when end time is less than start time, end time will be treated as time of next day +params = { plan_index = 0 } + +[[tasks.variants]] +condition = { type = "Time", end = "12:00:00" } # if start time is omitted, this condition will be matched if current time is less than end time +params = { plan_index = 1 } + +[[tasks.variants]] +condition = { type = "Time", start = "12:00:00" } # if end time is omitted, this condition will be matched if current time is greater than start time +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`. 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 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`. + +```toml +[[tasks]] +type = "Fight" + +# fight SL-8 on summer event +[[tasks.variants]] +params = { stage = "SL-8" } +condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } +# fight CE-6 on Tue, Thu, Sat if not on summer event +[[tasks.variants]] +condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"], timezone = "Official"} +params = { stage = "CE-6" } +# fight 1-7 otherwise +[[tasks.variants]] +params = { stage = "1-7" } +``` + +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. + +Beside of above basic condition, `{ type = "And", conditions = [...] }` `{ type = "Or", conditions = [...] }`, and `{ type = "Not", condition = ... }` can be used for logical combination of conditions. + +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]] +name = "Infrast (6 plan for 2 days)" +type = "Infrast" + +[tasks.params] +mode = 10000 +facility = ["Trade", "Reception", "Mfg", "Control", "Power", "Office", "Dorm"] +dorm_trust_enabled = true +filename = "normal.json" + +# First shift, 04:00:00 - 12:00:00 on the first day +[[tasks.variants]] +condition = { + type = "And", + conditions = [ + # 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 ` + # 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 } + +# The second shift, 12:00:00 - 20:00:00 on the first day +[[tasks.variants]] +condition = { + type = "And", + conditions = [ + { type = "DayMod", divisor = 2, remainder = 0 }, + { type = "Time", start = "12:00:00", end = "20:00:00" }, + ] +} +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, otherwise the second day 00:00:00 - 04:00:00 will not be matched +condition = { + type = "Or", + conditions = [ + { type = "And", conditions = [ + { type = "DayMod", divisor = 2, remainder = 0 }, + { type = "Time", start = "20:00:00" }, + ] }, + { type = "And", conditions = [ + { type = "DayMod", divisor = 2, remainder = 1 }, + { type = "Time", end = "04:00:00" }, + ] }, + ] +} +params = { plan_index = 2 } + +# The fourth shift, 04:00:00 - 12:00:00 on the second day +[[tasks.variants]] +condition = { + type = "And", + conditions = [ + { type = "DayMod", divisor = 2, remainder = 1 }, + { type = "Time", start = "04:00:00", end = "12:00:00" }, + ] +} +params = { plan_index = 3 } + +# The fifth shift, 12:00:00 - 20:00:00 on the second day +[[tasks.variants]] +condition = { + type = "And", + conditions = [ + { type = "DayMod", divisor = 2, remainder = 1 }, + { type = "Time", start = "12:00:00", end = "20:00:00" }, + ] +} +params = { plan_index = 4 } + +# The sixth shift, 20:00:00 (second day) - 04:00:00 (new first day) +[[tasks.variants]] +condition = { + type = "Or", + conditions = [ + { type = "And", conditions = [ + { type = "DayMod", divisor = 2, remainder = 1 }, + { type = "Time", start = "20:00:00" }, + ] }, + { type = "And", conditions = [ + { type = "DayMod", divisor = 2, remainder = 0 }, + { type = "Time", end = "04:00:00" }, + ] }, + ] +} +params = { plan_index = 5 } +``` + +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 of matching variants can be changed by `strategy` field: + +```toml +[[tasks]] +type = "Fight" +strategy = "merge" # or "first" (default) + +# use all expiring medicine on Sunday night +[[tasks.variants]] +params = { expiring_medicine = 1000 } +[tasks.variants.condition] +type = "And" +conditions = [ + { type = "Time", start = "18:00:00" }, + { type = "Weekday", weekdays = ["Sun"] }, +] + +# fight 1-7 by default +[[tasks.variants]] +params = { stage = "1-7" } + +# fight CE-6 on Tue, Thu, Sat if not on summer event +[[tasks.variants]] +condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } +params = { stage = "CE-6" } + +# fight SL-8 on summer event +[[tasks.variants]] +params = { stage = "SL-8" } +condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } +``` + +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 in some conditions: + +```toml +# Mall after 18:00 +[[tasks]] +type = "Mall" + +[[tasks.variants]] +condition = { type = "Time", start = "18:00:00" } +``` + +### User input + +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]] +type = "Fight" + +# Select a stage to fight +[[tasks.variants]] +condition = { type = "DateTime", start = "2023-08-01T16:00:00", end = "2023-08-21T03:59:59" } + +# Set the stage to a `Select` type with alternatives and description +[tasks.variants.params.stage] +# the alternatives of stage, at least one alternative should be given +# the element of alternatives can be a single value or a table with `value` and `desc` fields· +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 value will be re-prompt +description = "a stage to fight in summer event" # description of the input, optional +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]] +condition = { type = "Weekday", weekdays = ["Tue", "Thu", "Sat"] } +params = { stage = "CE-6" } + +# Input a stage to fight +[[tasks.variants]] + +# 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, user can input empty value to re-prompt) +description = "a stage to fight" # description of the input, optional +[tasks.variants.params.medicine] +# dependency of parameters, the key is the name of parameter, the value is the expected value of dependency parameter +# when set, the parameter will be required to input only if all dependency parameters are satisfied +deps = { 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 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. + +`--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 + +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: + +```toml +[connection] +preset = "MuMuPro" +adb_path = "adb" +device = "emulator-5554" +config = "CompatMac" + +[resource] +global_resource = "YoStarEN" +platform_diff_resource = "iOS" +user_resource = true + +[static_options] +cpu_ocr = false +gpu_ocr = 1 + +[instance_options] +touch_mode = "MAATouch" +deployment_with_pause = false +adb_lite_enabled = false +kill_adb_on_exit = false +``` + +### Connection + +The `connection` section is used to specify how to connect to the game: + +```toml +[connection] +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 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 some common emulators, you can use `preset` to use predefined configurations: + +```toml +[connection] +preset = "MuMuPro" +adb_path = "/path/to/other/adb" # override predefined adb executable path +address = "127.0.0.1:7777" # override the predefined address +``` + +Currently, there is only one preset `MuMuPro` for emulators. Issue and PR are welcome for the new preset. + +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 is used to specify the resource to use: + +```toml +[resource] +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 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 is used to configure MAA static options: + +```toml +[static_options] +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 is used to configure MAA instance options: + +```toml +[instance_options] +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: If you connect to the game with `PlayCover`, the `touch_mode` will be ignored and `MacPlayTools` will be used. + +## CLI related configurations + +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 +[core] +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 install MaaCore library +resource = false # whether install resource resource + +# CLI update configurations +[cli] +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/" +# 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 install maa-cli binary + + +# hot update resource configurations +[resource] +auto_update = true # whether auto update resource before running task +backend = "libgit2" # the backend of resource, can be "libgit2" or "git" + +# the remote of resource +[resource.remote] +branch = "main" # the branch of remote repository +# the url of remote repository, when using ssh, you should set ssh_key field +url = "https://github.com/MaaAssistantArknights/MaaResource.git" +# url = "git@github.com:MaaAssistantArknights/MaaResource.git" +# ssh_key = "~/.ssh/id_ed25519" # path to ssh key +``` + +**NOTE**: + +- 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 of config file + +- [Example configuration][example-config]; +- [Configuration used by maintainer][wangl-cc-dotfiles]. + +## JSON schema + +The JSON schema of configuration files can be found at [`schemas` directory][schema-dir]: + +- 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 the help of JSON schema, you can get auto-completion and validation in some editors with plugins. + +[task-types]: ../3.1-INTEGRATION.md#list-of-task-types +[emulator-ports]: ../1.2-FAQ.md#common-adb-ports-for-popular-android-emulators +[playcover-doc]: ../1.4-EMULATOR_SUPPORTS_FOR_MAC.md#✅-playcover-the-software-runs-most-fluently-for-its-nativity-🚀 +[example-config]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/maa-cli/config_examples +[wangl-cc-dotfiles]: https://github.com/wangl-cc/dotfiles/tree/master/.config/maa +[schema-dir]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/maa-cli/schemas/ +[task-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/maa-cli/schemas/task.schema.json +[asst-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/maa-cli/schemas/asst.schema.json +[cli-schema]: https://github.com/MaaAssistantArknights/maa-cli/blob/main/maa-cli/schemas/cli.schema.json + + diff --git a/docs/en-us/user_manual_for_cli/cli-faq.md b/docs/en-us/user_manual_for_cli/cli-faq.md new file mode 100644 index 0000000000..36e9777a8e --- /dev/null +++ b/docs/en-us/user_manual_for_cli/cli-faq.md @@ -0,0 +1,27 @@ +--- +order: 5 +icon: ph:question-fill +--- + +# FAQs for maa-cli + +## 1. How to use `$HOME/.config/maa` as the configuration directory on macOS? + +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" +ln -s "$HOME/.config/maa" "$(maa dir config)" +``` + +## 2. Strange logs appear during running, how to disable them? + +When running the maa-cli task, you may see some logs that look like this: + +```plaintext +[INFO] ... /fastdeploy/runtime.cc(544)::Init Runtime initialized with Backend::ORT in Device::CPU. +``` + +This log is output by `fastdeploy`, which is a dependency of MaaCore. For the officially compiled MaaCore, this log cannot be closed. However, if you are using a package manager to install maa-cli, you can try installing the package manager's version of MaaCore which uses a newer version of `fastdeploy` without logs enabled by default. + + diff --git a/docs/en-us/user_manual_for_cli/cli-install.md b/docs/en-us/user_manual_for_cli/cli-install.md new file mode 100644 index 0000000000..0dcb591e82 --- /dev/null +++ b/docs/en-us/user_manual_for_cli/cli-install.md @@ -0,0 +1,120 @@ +--- +order: 2 +icon: material-symbols:download +--- + +# Install and Build maa-cli + +There are multiple ways to install maa-cli, including package managers, precompiled binaries, and building from source with `cargo`. + +## Install via Package Manager + +For macOS and supported Linux distributions, it is recommended to install maa-cli using a package manager. + +### macOS + +Homebrew users can install maa-cli via the unofficial [tap](https://github.com/MaaAssistantArknights/homebrew-tap/): + +- Stable release: + + ```bash + brew install MaaAssistantArknights/tap/maa-cli + ``` + +- Beta releases: + + ```bash + brew install MaaAssistantArknights/tap/maa-cli-beta + ``` + +### Linux + +- Arch Linux users can install the [AUR package](https://aur.archlinux.org/packages/maa-cli/): + + ```bash + yay -S maa-cli + ``` + +- ❄️ Nix users can run directly: + + ```bash + # Stable release + nix run nixpkgs#maa-cli + ``` + + ```bash + # Nightly build + nix run github:Cryolitia/nur-packages#maa-cli-nightly + ``` + + 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. + +## Precompiled Binaries + +If package managers are not available on your system or you prefer not to use them, you can download the precompiled binaries for your platform from the following links. After decompressing, place the executable file in your `PATH` to use. + +- [macOS](https://github.com/MaaAssistantArknights/maa-cli/releases/latest/download/maa_cli-v0.4.5-universal-apple-darwin.zip) +- [Linux x86_64 (x64, amd64)](https://github.com/MaaAssistantArknights/maa-cli/releases/latest/download/maa_cli-v0.4.5-x86_64-unknown-linux-gnu.tar.gz) +- [Linux aarch64 (arm64)](https://github.com/MaaAssistantArknights/maa-cli/releases/latest/download/maa_cli-v0.4.5-aarch64-unknown-linux-gnu.tar.gz) +- [Windows x86_64 (x64, amd64)](https://github.com/MaaAssistantArknights/maa-cli/releases/latest/download/maa_cli-v0.4.5-x86_64-pc-windows-msvc.zip) + +If your platform is not listed above, you can try to compile and install it yourself (see below). + +## Build from Source + +Rust developers can compile and install maa-cli themselves via `cargo`: + +- Stable version: + + ```bash + cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --tag stable --locked + ``` + +- Development version: + + ```bash + cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked + ``` + +### Features + +When compiling from source, you can disable the default features with `--no-default-features` and then enable specific features with `--features`. The available features are: + +- `cli_installer`: Provide `maa self update` command to update self, this feature is enabled by default; +- `core_installer`: Provide `maa install` and `maa update` commands to install and update MaaCore and resources, this feature is enabled by default; +- `git2`: Provide `libgit2` resource backend, this feature is enabled by default; +- `vendored-openssl`: Build OpenSSL library by self instead of using system library, this feature is disabled by default; + +## Install MaaCore + +maa-cli only provides an interface for MaaCore, it needs MaaCore and resources to run tasks, which can be installed by maa-cli once it is installed: + +```bash +maa install +``` + +For users who installed via package managers, MaaCore can be installed via package managers: + +- Homebrew： + + ```bash + brew install MaaAssistantArknights/tap/maa-core + ``` + +- Arch Linux： + + ```bash + yay -S maa-assistant-arknights + ``` + +- Nix： + + ```bash + nix-env -iA nixpkgs.maa-assistant-arknights + ``` + +**NOTE**: Only users who installed maa-cli via package managers can install MaaCore via package managers. Otherwise, please use the `maa install` command to install. In addition, the `maa install` downloads the official precompiled MaaCore, while the MaaCore installed by package managers has different compilation options and dependency versions from the official precompiled version. This does not affect the use of maa-cli but may cause differences in the functionality and performance of MaaCore. For example, the MaaCore installed by package managers uses a newer version of `fastdeploy`, while the official precompiled MaaCore uses an older version of `fastdeploy`. In the new version of `fastdeploy`, logs can be hidden, which can eliminate some unnecessary log output. + + diff --git a/docs/en-us/user_manual_for_cli/cli-intro.md b/docs/en-us/user_manual_for_cli/cli-intro.md new file mode 100644 index 0000000000..5ef44940ea --- /dev/null +++ b/docs/en-us/user_manual_for_cli/cli-intro.md @@ -0,0 +1,23 @@ +--- +order: 1 +icon: material-symbols:toc +--- + +# maa-cli + +A simple CLI for [MAA][maa-home] written in Rust. + +## Features + +- Run predefined or custom tasks, like `maa fight` or `maa run `; +- Install and update MaaCore and resources with `maa install` and `maa update`; +- Update self with `maa self update`. + +## Documentation + +- [Installation and Compilation](cli-install.md) +- [Usage](cli-usage.md) +- [Configuration](cli-config.md) +- [FAQ](cli-faq.md) + +[maa-home]: https://github.com/MaaAssistantArknights/MaaAssistantArknights diff --git a/docs/en-us/user_manual_for_cli/cli-usage.md b/docs/en-us/user_manual_for_cli/cli-usage.md new file mode 100644 index 0000000000..ec1513d633 --- /dev/null +++ b/docs/en-us/user_manual_for_cli/cli-usage.md @@ -0,0 +1,91 @@ +--- +order: 3 +icon: material-symbols:summarize +--- + +# Use maa-cli + +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, just run the following commands: + +```bash +maa install # Install MaaCore and resources +maa update # Update MaaCore and resources +``` + +## Update maa-cli itself + +maa-cli can update itself, just run the following command: + +```bash +maa self update +``` + +**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. + +## Run Tasks + +Once MaaCore is installed, you can run tasks directly without additional configuration. The default configuration may not be suitable for all users. If you encounter problems when running tasks, you can refer to the [Configuration Document][config-core] to modify the configuration. + +### Predefined tasks + +- `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`: close the game client; +- `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 `: run a "copilot" task, the `maa_uri` is the URI of a copilot task; it can be `maa://1234` or local file path; +- `maa roguelike [theme]`: run a "roguelike" task, the `theme` is the theme of roguelike, and available themes are `Phantom`, `Mizuki` and `Sami`. + +The above tasks accept some parameters, you can view the specific parameters by `maa --help`. + +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 YoStarEN && maa fight BB-7 -m 3 && maa closedown +``` + +### Custom Tasks + +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 `, where `` is the name of the custom task, excluding the extension. + +### Task Summary + +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, 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 the task summary, you can turn it off by `--no-summary`. + +### Loggings + +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`. + +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`. + +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 + +Except for the above subcommands, maa-cli also provides other subcommands: + +- `maa list`: list all available tasks; +- `maa 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 [output]`: convert a file in `JSON`, `YAML`, or `TOML` format to another format; +- `maa complete `: 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 [-t ]`: 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. + +More command usage can be viewed by `maa help`, and the usage of specific commands can be viewed by `maa help `. + +[config-core]: cli-config.md#MaaCore-related-configurations +[custom-task]: cli-config.md#custom-task + + diff --git a/docs/用户手册/CLI使用指南/cli-config.md b/docs/用户手册/user_manual_for_cli/cli-config.md similarity index 96% rename from docs/用户手册/CLI使用指南/cli-config.md rename to docs/用户手册/user_manual_for_cli/cli-config.md index c0178f2728..475e52330a 100644 --- a/docs/用户手册/CLI使用指南/cli-config.md +++ b/docs/用户手册/user_manual_for_cli/cli-config.md @@ -3,7 +3,7 @@ order: 4 icon: material-symbols:settings --- -# 配置 CLI +# 配置 maa-cli ## 配置目录 @@ -279,7 +279,9 @@ description = "medicine to use" ## MaaCore 相关配置 -和 MaaCore 相关的配置需要放在 `$MAA_CONFIG_DIR/asst.toml` 中。目前其包含的配置有： +和 MaaCore 相关的配置需要放在 `$MAA_CONFIG_DIR/profiles` 目录中。该目录下的每一个文件都是一个配置文件，你可以通过 `-p` 或者 `--profile` 选项来指定配置文件名，不指定时尝试读取 `default` 配置文件。 + +目前支持的配置字段如下： ```toml [connection] @@ -315,7 +317,7 @@ address = = "emulator-5554" # 连接地址，比如 "emulator-5554" 或者 "127. config = "General" # 连接配置，通常不需要修改 ``` -`adb_path` 是 `adb` 可执行文件的路径，你可以指定其路径，或者将其添加到环境变量 `PATH` 中，以便 MaaCore 可以找到它。大多数模拟器自带 `adb`，你可以直接使用其自带的 `adb`，而不需要额外安装，否则你需要自行安装 `adb`。`address` 是 `adb` 的连接地址。对于模拟器，你可以使用 `127.0.0.1:[端口号]`，常用的模拟器端口号参见[常见问题][emulator-ports]。`config` 用于指定一些平台和模拟器相关的配置。对于 Linux 他默认为 `CompatPOSIXShell`，对于 macOS 他默认为 `CompatMac`，对于 Windows 他默认为 `General`。更多可选配置可以在资源文件夹中的 `config.json` 文件中找到。 +`adb_path` 是 `adb` 可执行文件的路径，你可以指定其路径，或者将其添加到环境变量 `PATH` 中，以便 MaaCore 可以找到它。大多数模拟器自带 `adb`，你可以直接使用其自带的 `adb`，而不需要额外安装，否则你需要自行安装 `adb`。`address` 是 `adb` 的连接地址。对于模拟器，你可以使用 `127.0.0.1:[端口号]`，常用的模拟器端口号参见[常见问题][emulator-ports]。如果你没有指定 `address`，那么会尝试通过 `adb devices` 来获取连接的设备，如果有多个设备连接，那么将会使用第一个设备，如果没有找到任何设备，那么将会尝试连接到 `emulator-5554`。`config` 用于指定一些平台和模拟器相关的配置。对于 Linux 他默认为 `CompatPOSIXShell`，对于 macOS 他默认为 `CompatMac`，对于 Windows 他默认为 `General`。更多可选配置可以在资源文件夹中的 `config.json` 文件中找到。 对于一些常用的模拟器，你可以直接使用 `preset` 来使用预设的配置： diff --git a/docs/用户手册/CLI使用指南/cli-faq.md b/docs/用户手册/user_manual_for_cli/cli-faq.md similarity index 98% rename from docs/用户手册/CLI使用指南/cli-faq.md rename to docs/用户手册/user_manual_for_cli/cli-faq.md index 22ecd930d9..7c2ebf0fe9 100644 --- a/docs/用户手册/CLI使用指南/cli-faq.md +++ b/docs/用户手册/user_manual_for_cli/cli-faq.md @@ -3,7 +3,7 @@ order: 5 icon: ph:question-fill --- -# 常见问题 +# maa-cli 常见问题 ## 1. 如何在 macOS 上使用 `$HOME/.config/maa` 作为配置文件目录？ diff --git a/docs/用户手册/CLI使用指南/cli-install.md b/docs/用户手册/user_manual_for_cli/cli-install.md similarity index 100% rename from docs/用户手册/CLI使用指南/cli-install.md rename to docs/用户手册/user_manual_for_cli/cli-install.md diff --git a/docs/用户手册/CLI使用指南/cli-intro.md b/docs/用户手册/user_manual_for_cli/cli-intro.md similarity index 93% rename from docs/用户手册/CLI使用指南/cli-intro.md rename to docs/用户手册/user_manual_for_cli/cli-intro.md index ad77ffc21e..369a778f06 100644 --- a/docs/用户手册/CLI使用指南/cli-intro.md +++ b/docs/用户手册/user_manual_for_cli/cli-intro.md @@ -1,6 +1,6 @@ --- order: 1 -icon: material-symbols:summarize +icon: material-symbols:toc --- # maa-cli diff --git a/docs/用户手册/CLI使用指南/cli-usage.md b/docs/用户手册/user_manual_for_cli/cli-usage.md similarity index 56% rename from docs/用户手册/CLI使用指南/cli-usage.md rename to docs/用户手册/user_manual_for_cli/cli-usage.md index d12200cb83..6e2338f66e 100644 --- a/docs/用户手册/CLI使用指南/cli-usage.md +++ b/docs/用户手册/user_manual_for_cli/cli-usage.md @@ -1,6 +1,6 @@ --- order: 3 -icon: material-symbols:format_list_bulleted +icon: material-symbols:summarize --- # 使用 maa-cli @@ -28,7 +28,7 @@ maa self update ## 运行任务 -maa-cli 通过调用 MaaCore 来完成任务，这些包括一些预定义的任务和用户自定义的任务。 +一旦完成了 MaaCore 的安装，通常情况下，你无需额外配置就可以直接运行任务。默认配置可能不适用于所有用户，如果你在运行任务时遇到问题，你可以参考 [配置文档][config-core] 修改配置。 ### 预定义任务 @@ -40,11 +40,17 @@ maa-cli 通过调用 MaaCore 来完成任务，这些包括一些预定义的任 - `maa copilot `: 运行自动战斗任务，其中 `` 是作业的 URI，其可以是 `maa://1234` 或者本地文件路径 `./1234.json`； - `maa roguelike [theme]`: 自动集成战略，`[theme]` 是集成战略的主题，可选值为 `Phantom`，`Mizuki` 以及 `Sami`； -### 用户自定义任务 +上述任务接受一些参数，你可以通过 `maa --help` 来查看具体的参数。 -你可以通过 `maa run ` 来运行自定义任务。这里的 `` 是一个自定义任务名， -自定义任务通过配置文件定义，具体配置文件的位置和编写方式请参考 [自定义任务文档][custom-task]. -在定义好自定义任务后，你可以通过 `maa list` 来列出所有可用的任务。 +对于官服玩家，如果你想要打开游戏，使用 3 个理智药刷 BB-7，然后关闭游戏，你可以运行以下命令： + +```bash +maa startup Official && maa fight BB-7 -m 3 && maa closedown +``` + +### 自定义任务 + +由于MAA支持的任务繁多，maa-cli无法提供所有任务的预定义选项。除此之外，你可能需要像上述的例子一样运行多个任务。为了解决这个问题，maa-cli提供了自定义任务的功能。自定义任务能够组合不同的任务，并且更精细地控制每个任务的参数以及执行顺序。此外，自定义任务支持条件判断，可以根据条件来决定是否执行某个任务，或者以何种参数执行某个任务。这可以用于自动化你的日常任务。自定义任务通过配置文件定义，具体配置文件的位置和编写方式请参考 [自定义任务文档][custom-task]。在编写好配置文件后，你可以通过 `maa run ` 来运行自定义任务，这里的 `` 是一个自定义任务文件名，不包括扩展名。 ### 任务总结 @@ -66,6 +72,22 @@ maa-cli 默认会向标准误 (stderr) 输出日志。`--log-file` 选项可以 默认情况下，所有输出的日志会包含时间戳和日志级别的前缀。你可以通过环境变量 `MAA_LOG_PREFIX` 来改变这个行为。设置为 `Always` 时，总是会包含前缀，设置为 `Auto` 时输出到日志文件时会包含前缀，而输出到 stderr 时不会包含前缀，而设置为 `Never` 时即使是写入日志文件时也不会包含前缀。 +### 其他子命令 + +除了上述的命令外，maa-cli 还提供了其他一些子命令： + +- `maa list`: 列出所有可用的任务； +- `maa dir `: 获取特定目录的路径，比如 `maa dir config` 可以用来获取配置目录的路径; +- `maa version`: 获取 `maa-cli` 以及 `MaaCore` 的版本信息； +- `maa convert [output]`: 将 `JSON`，`YAML` 或者 `TOML` 格式的文件转换为其他格式; +- `maa complete `: 生成自动补全脚本; +- `maa activity [client]`: 获取游戏的当前活动信息，`client` 是客户端类型，默认为 `Official`。 +- `maa cleanup`: 清除 `maa-cli` 和 `MaaCore` 的缓存。 +- `maa import [-t ]:` 导入配置文件，`file` 是配置文件的路径。`-t` 选项可以指定配置文件的类型，如 `cli`, `profile`, `infrast` 等。 + +更多命令的使用方法可以通过 `maa help` 查看，具体命令的使用方法可以 通过 `maa help ` 查看。 + +[config-core]: cli-config.md#MaaCore-相关配置 [custom-task]: cli-config.md#自定义任务 diff --git a/src/maa-cli b/src/maa-cli index 7787841109..611040925a 160000 --- a/src/maa-cli +++ b/src/maa-cli @@ -1 +1 @@ -Subproject commit 7787841109c58bd72259113f9d96b61b7d1d6724 +Subproject commit 611040925a9940d981293a09bab7174d2304f326