MaaAssistantArknights/docs/en-us/1.6-USER_GUIDE_FOR_CLI.md

icon

icon
material-symbols:terminal

User Guide for CLI

Feature

• Define tasks by TOML, YAML or JSON file, then run it by maa run <task>;
• 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 download the latest Appimage.

Package manager

macOS

Install with Homebrew:

brew install MaaAssistantArknights/tap/maa-cli

Linux

ArchLinux user can install AUR package:

yay -S maa-cli

For LinuxBrew user, you can install with LinuxBrew:

brew install MaaAssistantArknights/tap/maa-cli

Prebuilt binary

You can install CLI by download prebuilt binary from maa-cli release page and extract it to your favorite location. The filename for different platform is:

Operation System	Architecture	Filename
Linux	x86_64	maa_cli-x86_64-unknown-linux-gnu.tar.gz
	aarch64	maa_cli-aarch64-unknown-linux-gnu.tar.gz
macOS	x86_64	maa_cli-universal-apple-darwin.zip
	aaarch64
Windows	x86_64	maa_cli-x86_64-pc-windows-msvc.zip

Build from source

You can also build from source by yourself with cargo:

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:

maa install

Usage

Commands

The main feature of maa-cli is to run tasks, you can run a task by maa run <task>. Here <task> 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:

[[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 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:

[[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.

[[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:

[[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:

# 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:

[[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:

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:

[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:

[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:

[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:

[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.