mirror/appium
1
0
Fork 0
mirror of https://github.com/appium/appium.git synced 2025-12-30 06:40:02 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs(appium): enhance CLI pages (#21535)

Browse Source 
* docs: update env vars page

* docs: update env vars page some more

* docs: turn CLI args page into server subcommand reference page

* docs: update CLI setup page

* docs: adjust order of CLI setup options

* docs: move help option to index page

* docs: merge CLI alias column into main column

* docs: add small headings to CLI setup

* docs: update most of the CLI extensions page

* docs: update remaining parts of CLI extension page

* docs: minor CLI adjustments
This commit is contained in:
Edgars Eglītis
2025-08-30 22:57:27 +03:00
committed by GitHub
parent d280e2af0f
commit 6a547ef055
12 changed files with 354 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -133,7 +133,7 @@ appium plugin uninstall <plugin-name>
## Server Command Line Interface
In order to start sending commands to the Appium server, it must be running on the URL and port
where your client library expects it to listen. [Appium's command-line interface](http://appium.io/docs/en/latest/cli/args/)
where your client library expects it to listen. [Appium's command-line interface](http://appium.io/docs/en/latest/cli/server/)
is used to launch and configure the server:
```bash

2
packages/appium/README.md
View File

@@ -133,7 +133,7 @@ appium plugin uninstall <plugin-name>
## Server Command Line Interface
In order to start sending commands to the Appium server, it must be running on the URL and port
where your client library expects it to listen. [Appium's command-line interface](http://appium.io/docs/en/latest/cli/args/)
where your client library expects it to listen. [Appium's command-line interface](http://appium.io/docs/en/latest/cli/server/)
is used to launch and configure the server:
```bash

2
packages/appium/docs/base-mkdocs.yml
View File

@@ -33,7 +33,7 @@ plugins:
'commands/storage-plugin.md': 'reference/api/storage-plugin.md'
'commands/universal-xml-plugin.md': 'reference/api/universal-xml-plugin.md'
'cli/index.md': 'reference/cli/index.md'
'cli/args.md': 'reference/cli/args.md'
'cli/args.md': 'reference/cli/server.md'
'cli/env-vars.md': 'reference/cli/env-vars.md'
'cli/extensions.md': 'reference/cli/extensions.md'
'cli/setup.md': 'reference/cli/setup.md'

2
packages/appium/docs/en/guides/migrating-1-to-2.md
View File

@@ -125,7 +125,7 @@ path to `/`, therefore the default server URL is now `http://localhost:4723/`.
In your test scripts, change the base path of the target server URL from `/wd/hub` to `/`.
Alternatively, you can retain the Appium 1 base path by launching Appium with the
`--base-path=/wd/hub` [command-line argument](../reference/cli/args.md).
`--base-path=/wd/hub` [command-line argument](../reference/cli/server.md).
### Server Port 0 No Longer Supported

2
packages/appium/docs/en/guides/security.md
View File

@@ -22,7 +22,7 @@ this is the responsibility of the server admin who configures and launches the A
## Security Server Args
The [Server CLI Args](../reference/cli/args.md) doc outlines three relevant arguments which may be passed to
The [Server CLI](../reference/cli/server.md) doc outlines three relevant arguments which may be passed to
Appium when starting it from the command line:
|<div style="width:10em">Parameter</div>|Description|

70
packages/appium/docs/en/reference/cli/args.md
View File

@@ -1,70 +0,0 @@
---
hide:
- toc
title: Server Command-Line Arguments
---
To start the Appium server, you may either run `appium` or `appium server`. The `server` subcommand
is considered to be the default, so if you omit it, Appium will interpret this as your request to
run the Appium server.
The invocation of `appium` (or `appium server`) can take a number of arguments, which are detailed
below.
!!! note
All of these arguments can be set via a [Configuration File](../../guides/config.md) instead if
you want. Any arguments set on the command line will override any arguments found in
a configuration file.
|<div style="width:12em">Argument</div>|Description|Type|<div style="width:8em">Default</div>|Aliases|
|--|--|--|--|--|
|`--address`|IP address to listen on|string|`0.0.0.0`|`-a`|
|`--allow-cors`|Whether the Appium server should allow web browser connections from any host|boolean|`false`||
|`--allow-insecure`|Set which [insecure features](../../guides/security.md) are allowed to run in this server's sessions. Most features are defined on a driver level; see driver documentation for more details. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`.|array<string>|`[]`||
|`--base-path`|Base path to use as the prefix for all webdriver routes running on the server|string|`""`|`-pa`|
|`--callback-address`|Callback IP address (default: same as `--address`)|string||`-ca`|
|`--callback-port`|Callback port (default: same as `--port`) (Value must be between `1` and `65535`)|integer|`4723`|`-cp`|
|`--config`|Path to an [Appium configuration JSON file](../../guides/config.md)|string|||
|`--debug-log-spacing`|Add exaggerated spacing in logs to help with visual inspection|boolean|`false`||
|`--default-capabilities`|Set the default desired capabilities, which will be set on each session unless overridden by received capabilities. If a string, a path to a JSON file containing the capabilities, or raw JSON.|object||`-dc`|
|`--deny-insecure`|Set which [insecure features](../../guides/security.md) are not allowed to run in this server's sessions. Most features are defined on a driver level; see driver documentation for more details. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both.|array<string>|`[]`||
|`--driver`|Driver-specific configuration. Keys should correspond to driver package names|object|||
|`--drivers-import-chunk-size`|The maximum amount of drivers that could be imported in parallel on server startup|number|`3`||
|`--keep-alive-timeout`|Number of seconds the Appium server should apply as both the keep-alive timeout and the connection timeout for all requests. Setting this to `0` disables the timeout.|integer|`600`|`-ka`|
|`--request-timeout`|Number of seconds the Appium server should apply for receiving the entire HTTP request from the client. A value of 0 disables the timeout. Set it to a non-zero value to protect against potential Denial-of-Service attacks in case the server is deployed without a reverse proxy in front. HTTP requests that are running longer than allowed by this timeout would be rejected with the status code 408.|integer|`3600`||
|`--local-timezone`|Use local timezone for timestamps|boolean|`false`||
|`--log`|Also send log output to this file|string||`-g`|
|`--log-filters`|One or more log filtering rules|array|||
|`--log-level`|Log level (console[:file]) (Value must be one of: `info`, `info:debug`, `info:info`, `info:warn`, `info:error`, `warn`, `warn:debug`, `warn:info`, `warn:warn`, `warn:error`, `error`, `error:debug`, `error:info`, `error:warn`, `error:error`, `debug`, `debug:debug`, `debug:info`, `debug:warn`, `debug:error`)|string|`debug`||
|`--log-format`|Log format (Value must be to one of: `text`, `json`, `pretty_json`). If logs are printed as JSON then the text coloring is always disabled.|string|`text`||
|`--log-no-colors`|Do not use color in console output|boolean|`false`||
|`--log-timestamp`|Show timestamps in console output|boolean|`false`||
|`--long-stacktrace`|Add long stack traces to log entries. Recommended for debugging only.|boolean|`false`||
|`--no-perms-check`|Skip various permission checks on the server startup|boolean|`false`||
|`--nodeconfig`|Path to configuration JSON file to register Appium as a node with Selenium Grid 3; otherwise the configuration itself|string|||
|`--plugin`|Plugin-specific configuration. Keys should correspond to plugin package names|object|||
|`--plugins-import-chunk-size`|The maximum amount of plugins that could be imported in parallel on server startup|number|`7`||
|`--port`|Port to listen on (Value must be between `1` and `65535`)|integer|`4723`|`-p`|
|`--relaxed-security`|Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`.|boolean|`false`||
|`--session-override`|Enables session override (clobbering)|boolean|`false`||
|`--ssl-cert-path`|Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details|string|||
|`--ssl-key-path`|Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details|string|||
|`--strict-caps`|Cause sessions to fail if desired caps are sent in that Appium does not recognize as valid for the selected device|boolean|`false`||
|`--tmp`|Absolute path to directory Appium can use to manage temp files|string|Windows: `C:\Windows\Temp`<br>Others: `/tmp`||
|`--trace-dir`|Absolute path to directory Appium can use to save iOS instrument traces|string|`<tmp>/appium-instruments`||
|`--use-drivers`|A list of drivers to activate. By default, all installed drivers will be activated.|array<string>|`[]`||
|`--use-plugins`|A list of plugins to activate. To activate all plugins, the value should be an array with a single item `"all"`.|array<string>|`[]`||
|`--webhook`|Also send log output to this http listener|string||`-G`|
The following arguments are used for information retrieval, after which the server will automatically exit. They are therefore meant for reference or debug purposes.
|<div style="width:10em">Argument</div>|Description|Alias|
|--|--|--|
|`--help`|Print instructions on using the Appium command-line. This argument can also be used for any Appium subcommands.|`-h`|
|`--show-build-info`|Print detailed information on the Appium server version||
|`--show-config`|Print the current Appium server configuration details||
|`--show-debug-info`|Print information on the current environment: details about the operating system, Node.js, and Appium itself||
|`--version`|Print the Appium server version|`-v`|

39
packages/appium/docs/en/reference/cli/env-vars.md
View File

@@ -2,23 +2,30 @@
hide:
- toc
title: Server Environment Variables
title: Environment Variables
---
The primary way of configuring the Appium server is via [Command-Line Arguments](./args.md). However, some more
advanced features are toggled or configured via environment variables. To set environment
variables, refer to the documentation for your operating system and terminal. These are the
environment variables that the Appium server understands:
The primary ways of configuring the Appium server are via [Command-Line Arguments](./server.md) or
the [Config File](../../guides/config.md). However, some more advanced features are toggled or
configured via environment variables. To set environment variables, refer to the documentation for
your operating system and terminal.
|Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|Description|
These are the environment variables that the Appium server understands:
|<div style="width:18em">Variable</div>|Description|
|--------|-----------|
|`APPIUM_HOME`|By default, Appium creates a directory called `.appium` in the home directory for your system user. You can adjust the directory with this variable, as detailed in the [Managing Extensions](../../guides/managing-exts.md) guide.|
|`APPIUM_TMP_DIR`|By default, Appium uses a random temporary directory for many of its operations. If you wish to use a specific directory, you may do so by including an absolute path as the value of this variable. The behaviour is equivalent to using the `--tmp` CLI arg.|
|`APPIUM_PREFER_SYSTEM_UNZIP`|Set to `0` or `false` to request that Appium not use the `unzip` binary included on your system for unzipping downloaded apps or other artifacts. Instead it will use a JS-based unzip library. This could help on some systems with non-existent or non-standard `unzip` commands. Note that if unzipping fails using the system library, the fallback library will be attempted in any case, so setting this env var merely saves time in the event you know the system unzip will fail.|
|`APPIUM_HOST`|Same as the `--address` CLI arg|
|`APPIUM_PORT`|Same as the `--port` CLI arg|
|`APPIUM_RELOAD_EXTENSIONS`|Set to `1` to cause Appium to re-require extensions when new sessions are created. This is mostly useful for [building extensions](../../developing/build-drivers.md)|
|`APPIUM_OMIT_PEER_DEPS`|Adds `--omit=peer` to all the NPM commands run internally by Appium. Mostly an internal feature.|
|`APPIUM_APPS_CACHE_MAX_AGE`|Allows to set the maximum age (in minutes) for [cached applications](../../guides/caching.md). The default value is `60 * 24` (24 hours). Do not set it to a lower number than the duration of a single session startup.|
|`APPIUM_APPS_CACHE_MAX_ITEMS`|Allows to set the maximum amount of [cached applications](../../guides/caching.md). The default value is `1024`. Do not set it to a lower number than the amount of apps in all parallel sessions per process.|
|`APPIUM_APPS_CACHE_IGNORE_URL_QUERY`| If the above option is enabled then the 'search' part of the app URL will be cut off from cache keys. See the corresponding [feature request](https://discuss.appium.io/t/regarding-app-caching-when-using-aws-s3-presigned-urls/42713) for more details. Disabled by default.|
|`APPIUM_APPS_CACHE_IGNORE_URL_QUERY`|Set this to a truthy value to remove any query part of a URL when using it as a cache key. See the corresponding [feature request](https://discuss.appium.io/t/regarding-app-caching-when-using-aws-s3-presigned-urls/42713) for more details.|
|`APPIUM_APPS_CACHE_MAX_AGE`|Set the maximum age (in minutes) for [cached applications](../../guides/caching.md). Do not set it to a lower number than the duration of a single session startup. Default: `60 * 24` (24 hours)|
|`APPIUM_APPS_CACHE_MAX_ITEMS`|Set the maximum amount of [cached applications](../../guides/caching.md). Do not set it to a lower number than the amount of apps in all parallel sessions per process. Default: `1024`|
|`APPIUM_HOME`|Set the path to the Appium home directory, which is used for [Managing Extensions](../../guides/managing-exts.md). Default: `.appium` in the home directory of the current user|
|`APPIUM_OMIT_PEER_DEPS`|Set this to `1` to add `--omit=peer` to all the NPM commands run internally by Appium. Mostly an internal feature.|
|`APPIUM_RELOAD_EXTENSIONS`|Set this to a truthy value to cause Appium to re-require extensions when new sessions are created. This feature is mostly useful for [building extensions](../../developing/build-drivers.md).|
|`APPIUM_TMP_DIR`|Set the path to the directory used for temporary files. Same as the `--tmp` command line argument.|
Appium drivers and plugins may define additional environment variables. The following variables are
used by official plugins:
|<div style="width:13em">Variable</div>|Plugin|Description|
|--------|-----------|-----------|
|`APPIUM_STORAGE_KEEP_ALL`|`storage`|Set this to `1`, `true` or `yes` to preserve files in the storage after the server process is terminated. By default, stopping the server process also deletes all files in the storage.|
|`APPIUM_STORAGE_ROOT`|`storage`|Set the path to the directory used for storage. If set to an existing folder, all files in it will be retained after terminating the server, unless specified otherwise using `APPIUM_STORAGE_KEEP_ALL`.|

305
packages/appium/docs/en/reference/cli/extensions.md
View File

@@ -1,108 +1,83 @@
---
title: Extension Command-Line Usage
title: appium driver/plugin
---
<style>
ul[data-md-component="toc"] .md-nav {
display: none;
}
</style>
Appium allows for the flexible installation and management of various _extensions_, such as _drivers_
(which provide Appium with the capability to automate a given platform) and _plugins_ (which can
augment or alter the way individual Appium commands work). For a conceptual understanding of these
entities, please review the [Introduction](../../intro/index.md).
Provides management options for a specific extension (driver or plugin). Both the `appium driver` and
`appium plugin` subcommands support the same options.
Management of drivers and plugins is handled by Appium's Extension CLI (command-line interface).
The following sub-subcommands are supported: `doctor`, `install`, `list`, `run`, `update`,
and `uninstall`.
## `doctor`
Runs doctor checks for an installed extension, which validate whether the extension has its prerequisites
configured correctly. Note that not all extensions include doctor checks.
!!! note
This reference uses placeholders to refer to various options. Anywhere you see one of these
placeholders in the reference, ensure you replace it with the correct type of actual content.
If you maintain an Appium extension and would like to add Appium Doctor support for it, check
out the documentation on [Building Doctor Checks](../../developing/build-doctor-checks.md).
|Placeholder|Meaning|
#### Usage
```
appium {driver|plugin} doctor <extension-name>
```
|Argument|Description|
|--|--|
|`<ext-type>`|"Extension type". It should be either `driver` or `plugin`. All the Extension CLI commands can be used with either drivers or plugins, so you must specify which type of extension will be used|
|`<ext-name>`|"Extension name". This is the short name of the extension found in a call to `appium <ext-type> list`. This is distinct from the NPM package name of the extension or, in general, the "install spec" of the extension.|
|`<install-spec>`|"Install specification". This refers to the string used to indicate what extension Appium should install.|
|`<install-source>`|This refers to the method that Appium should use to install an extension.|
|`extension-name`|The short name of the installed extension|
## Commands
#### Options
All Extension CLI commands begin with `appium <ext-type>`, i.e., either `appium driver` or `appium
plugin`.
|Argument|Description|Type|
|--|--|--|
|`--json`|Return the result in JSON format|boolean|
All Extension CLI commands can take an optional `--json` argument, which will return the result of
the command as a machine-readable JSON string rather than the standard output, which is colourized
and tuned for human consumption.
#### Example
### `doctor`
- Run doctor checks for the UiAutomator2 driver:
Run doctor checks for the given extension, which validate whether the extension has its prerequisites
configured correctly. Note that not all extensions include doctor checks. See the
[Building Doctor Checks](../../developing/build-doctor-checks.md) tutorial for more details on
how to create them.
```
appium driver doctor uiautomator2
```
Usage:
## `install`
Installs an extension.
#### Usage
```
appium <ext-type> doctor <ext-name>
appium {driver|plugin} install <install-spec>
```
Required arguments:
- `<ext-type>`: must be `driver` or `plugin`
- `<ext-name>`: the name of the extension whose doctor checks you want to run
Optional arguments:
- `--json`: return the result in JSON format
Example (run doctor checks for the UiAutomator2 driver):
```
appium driver doctor uiautomator2
```
### `install`
Install an extension. If successful, respond with the short name of the extension which can be used
in other invocations of the Extension CLI. If the extension is a driver, also note which platforms
may be used with the driver.
Usage:
```
appium <ext-type> install <install-spec> [--source=<install-source>] [--package=<package-name>] [--json]
```
Required arguments:
- `<ext-type>`: must be `driver` or `plugin`
- `<install-spec>`: this is the name, location, and/or version of the extension you want to
install. Its possible values are dependent on the `<install-source>` (see below).
Optional arguments:
- `--source`: this directs Appium where to find your extension. See below for a table of possible
source types and corresponding install specification.
- `--package`: when `<install-source>` is `git` or `github`, `--package` is required. It should be
the Node.js package name of the extension. Without this information, Appium will not be able to
find the installed package.
- `--json`: return the result in JSON format
|Install source type|Behaviour|
|<div style="width:7em">Argument</div>|Description|
|--|--|
|None|This is the default behaviour when no `--source` is used. In this case, Appium will look at `<install-spec>` and match it against the name of extensions available when running `appium <ext-type> list`, i.e., against the officially recognized extension names. If found, it will install that extension at the latest version via NPM|
|`npm`|Install an extension based on its NPM package name. Here, `<install-spec>` must be the NPM package name with any additional NPM installation modifiers, like version (see below)|
|`github`|Install an extension via a GitHub spec of the form `<org>/<repo>`|
|`git`|Install an extension via a Git URL (e.g., `git+ssh://git-host.com/repo.git`)|
|`local`|Install an extension via a local path. This must be a path to the directory where the Node.js package information for the driver is located.|
|`install-spec`|The short name of an official extension, with optional `npm` version or tag modifier. If using the `--source` option, the expected format of this argument will change ([see below](#source-vs-install-spec)).|
#### NPM-based `<install-spec>`
#### Options
When Appium is installing an extension via NPM (as is the case when `--source` is either omitted or
set to `npm`), the `<install-spec>` can be complex, and can include any kind of information allowed
by `npm install`:
|Argument|Description|Type|
|--|--|--|
|`--json`|Return the result in JSON format|boolean|
|`--package`|The Node.js package name of the extension. Required if `--source` is set to `git` or `github`.|string|
|`--source`|The location where Appium should look for the given extension. Supported values are `git`, `github`, `local`, or `npm`. Changes the expected format of `install-spec` ([see below](#source-vs-install-spec)).|string|
- `[@scope]/<name>`
- `[@scope]/<name>@<version>`
- `[@scope]/<name>@<tag>`
- `[@scope]/<name>@<version range>`
#### Source vs Install Spec
|`source`|Format of `<install-spec>`|
|--|--|
|None|The short name of an official extension, with optional modifiers as supported by `npm install` (e.g. version or tag)|
|`git`|The Git URL of the extension|
|`github`|The GitHub repository URL of the extension|
|`local`|The local path to the extension containing its `package.json` file|
|`npm`|The name of the `npm` package, with optional modifiers as supported by `npm install` (e.g. version or tag)|
#### Examples
@@ -112,115 +87,153 @@ by `npm install`:
appium driver install xcuitest
```
- Install the XCUITest driver at version 4.11.1:
- Install the XCUITest driver at version 9.0.0:
```
appium driver install xcuitest@4.11.1
appium driver install xcuitest@9.0.0
```
- Install the `beta` version of the `@appium/fake-driver` from NPM:
- Install the `beta` version of `@appium/fake-driver` from `npm`:
```
appium driver install --source=npm @appium/fake-driver@beta
appium driver install @appium/fake-driver@beta --source=npm
```
- Install a locally-developed plugin:
```
appium plugin install --source=local /path/to/my/plugin
appium plugin install /path/to/my/plugin --source=local
```
### `list`
- Install the XCUITest driver from GitHub:
List installed and available extensions. "Available" extensions include those which are officially
recognized by the Appium team, but you are not limited to installing only the extensions displayed
in this list.
```
appium driver install https://github.com/appium/appium-xcuitest-driver --source=github --package=appium-xcuitest-driver
```
Usage:
- Install the XCUITest driver using a Git URL:
```
appium driver install git://github.com/appium/appium-xcuitest-driver.git --source=git --package=appium-xcuitest-driver
```
## `list`
Lists all installed extensions, plus all official extensions that are not installed.
#### Usage
```
appium <ext-type> list [--installed] [--updates] [--json]
appium {driver|plugin} list
```
Required arguments:
#### Options
- `<ext-type>`: must be `driver` or `plugin`
|<div style="width:7em">Argument</div>|Description|Type|
|--|--|--|
|`--installed`|Only list all installed extensions|boolean|
|`--json`|Return the result in JSON format|boolean|
|`--updates`|List all extensions along with information on whether newer versions are available. Only supported for extensions installed via `npm`.|boolean|
Optional arguments:
#### Example
- `--installed`: show only installed extensions, not installed plus available extensions
- `--updates`: for extensions installed via NPM, display a message if there are any updates
- `--json`: return the result in JSON format
- List all installed drivers and check if they have newer versions available:
### `run`
```
appium driver list --installed --updates
```
Run a script included in an extension package. Extension authors can include runnable scripts that
assist with setup or perform other tasks. These scripts are given names (called the `<script-name>`
in this reference) by extension authors and will generally be documented in extension
documentation.
## `run`
Usage:
Runs an extension script, which can assist with setup or perform other tasks. Note that not all
extensions include scripts.
#### Usage
```
appium <ext-type> run <ext-name> [--json] <script-name> [script-args]
appium {driver|plugin} run <extension-name> <script-name> [script-args]
```
Required arguments:
|Argument|Description|
|--|--|
|`extension-name`|The short name of the installed extension|
|`script-name`|The name of the script to be run|
|`script-args`|Any additional arguments passed to the script|
- `<ext-type>`: must be `driver` or `plugin`
- `<ext-name>`: the name of the extension whose script you want to run
- `<script-name>`: the name of the script the extension has published
#### Options
Optional arguments:
|Argument|Description|Type|
|--|--|--|
|`--json`|Return the result in JSON format|boolean|
- `script-args`: any arguments that Appium does not interpret as belonging to its own set of
arguments will be passed along to the extension script
- `--json`: return the result in JSON format
#### Example
Example (run the `reset` script included with the UiAutomator2 driver):
- Run the `reset` script included in the UiAutomator2 driver:
```
appium driver run uiautomator2 reset
```
## `update`
Updates one or more extensions. Only supported for extensions installed via `npm`. By default,
Appium will only update minor and patch versions, in order to prevent any breaking changes.
#### Usage
```
appium driver run uiautomator2 reset
appium {driver|plugin} update <extension-name>
```
### `update`
|Argument|Description|
|--|--|
|`extension-name`|The short name of the installed extension, or `installed` to update all installed extensions|
Update one or more extensions that have been installed via NPM. By default, Appium will not
automatically update any extension past a major version boundary, so as to prevent
unintended breaking changes.
#### Options
Usage:
|Argument|Description|Type|
|--|--|--|
|`--json`|Return the result in JSON format|boolean|
|`--unsafe`|Allow updates of major versions, which may cause breaking changes|boolean|
#### Examples
- Update the UiAutomator2 driver to its latest major version:
```
appium driver update uiautomator2 --unsafe
```
- Update all installed plugins:
```
appium plugin update installed
```
## `uninstall`
Removes an installed extension.
#### Usage
```
appium <ext-type> update <ext-name> [--unsafe] [--json]
appium {driver|plugin} uninstall <extension-name>
```
Required arguments:
|Argument|Description|
|--|--|
|`extension-name`|The short name of the installed extension|
- `<ext-type>`: must be `driver` or `plugin`
- `<ext-name>`: the name of the extension to update, or the string `installed` (which will update
all installed extensions)
#### Options
Optional arguments:
|Argument|Description|Type|
|--|--|--|
|`--json`|Return the result in JSON format|boolean|
- `--unsafe`: direct Appium to go ahead and update past a major version boundary
- `--json`: return the result in JSON format
#### Example
### `uninstall`
- Remove the `images` plugin:
Remove an installed extension.
Usage:
```
appium <ext-type> uninstall <ext-name> [--json]
```
Required arguments:
- `<ext-type>`: must be `driver` or `plugin`
- `<ext-name>`: the name of the extension to uninstall
Optional arguments:
- `--json`: return the result in JSON format
```
appium plugin uninstall images
```

38
packages/appium/docs/en/reference/cli/index.md
View File

@@ -6,22 +6,30 @@ title: Command Line Interface
---
Appium provides a command-line executable (`appium`), which can be used to configure and launch
the Appium server, as well as manage drivers and plugins.
the Appium server, as well as manage Appium extensions (drivers and plugins).
To start off, you can run `appium -v` or `appium --version` to return the installed version,
or run `appium -h` or `appium --help` to return the help message.
The executable has four main subcommands: `server`, `driver`, `plugin`, and `setup`. All subcommands
(and sub-subcommands) can be run with the `--help`/`-h` option for usage instructions.
The main `appium` executable provides the following subcommands:
<div class="grid cards" markdown>
1. `appium server` (or simply `appium`) - launch an Appium server
- [See here for accepted arguments](./args.md)
- For advanced features, [see here for accepted environment variables](./env-vars.md)
2. `appium driver` - manage Appium drivers
- [See here for details](./extensions.md)
3. `appium plugin` - manage Appium plugins
- [See here for details](./extensions.md)
4. `appium setup` - batch install a preset of drivers and plugins
- [See here for details](./setup.md)
- [__`appium server`__](./server.md) (or simply `appium`)
Like the main command, you can also run each subcommand with the `-h` or `--help` flag to learn
more about it.
Start an Appium server
- [__`appium driver`__](./extensions.md)
Manage individual drivers
- [__`appium plugin`__](./extensions.md)
Manage individual plugins
- [__`appium setup`__](./setup.md)
Manage multiple drivers/plugins
</div>
Appium also recognizes several [environment variables](./env-vars.md), which may be used for
advanced configuration.

76
packages/appium/docs/en/reference/cli/server.md Normal file
View File

@@ -0,0 +1,76 @@
---
hide:
- toc
title: appium server
---
Launches an Appium server.
```
appium server
```
You can also omit the `server` subcommand:
```
appium
```
### Options
!!! note
All of these options can also be set via a [Configuration File](../../guides/config.md). Options
set on the command line will override any options found in a configuration file.
|<div style="width:15em">Argument</div>|Description|Type|<div style="width:7em">Default</div>|
|--|--|--|--|
|`--address`, `-a`|IPv4/IPv6 address to listen on|string|`0.0.0.0`|
|`--allow-cors`|Allow web browser connections from any host|boolean|`false`|
|`--allow-insecure`|List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`.|array<string>|`[]`|
|`--base-path`, `-pa`|Base path to use as the prefix for all webdriver routes running on the server|string|`""`|
|`--callback-address`, `-ca`|Callback IP address|string|`0.0.0.0`|
|`--callback-port`, `-cp`|Callback port|integer|`4723`|
|`--config`|Path to an [Appium configuration JSON file](../../guides/config.md)|string||
|`--debug-log-spacing`|Add exaggerated spacing in logs to help with visual inspection|boolean|`false`|
|`--default-capabilities`, `-dc`|Capabilities that will be used for each session, unless overridden by received capabilities|object||
|`--deny-insecure`|List of [insecure features](../../guides/security.md) that should be disabled in this server's sessions. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both.|array<string>|`[]`|
|`--driver`|Driver-specific configuration. Keys should correspond to driver package names|object||
|`--drivers-import-chunk-size`|Maximum number of drivers that can be imported in parallel on server startup|number|`3`|
|`--keep-alive-timeout`, `-ka`|Timeout (in seconds) to use as both the keep-alive timeout and the connection timeout for all client requests. Disabled if set to `0`.|integer|`600`|
|`--request-timeout`|Timeout (in seconds) for waiting to receive the entire HTTP request from the client. Disabled if set to `0`. Requests exceeding this timeout will be rejected with the code `HTTP 408`.|integer|`3600`|
|`--local-timezone`|Use local timezone for log timestamps|boolean|`false`|
|`--log`, `-g`|Path to a file where the server logs should be output. This does not affect output on the console.|string||
|`--log-filters`|List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details.|array||
|`--log-level`|The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively.|string|`debug`|
|`--log-format`|The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors.|string|`text`|
|`--log-no-colors`|Disable colors in the server log|boolean|`false`|
|`--log-timestamp`|Show timestamps in the server log|boolean|`false`|
|`--long-stacktrace`|Add long stack traces to log entries. Recommended for debugging only.|boolean|`false`|
|`--no-perms-check`|Skip various permission checks on the server startup|boolean|`false`|
|`--nodeconfig`|JSON configuration for registering Appium as a node with Selenium Grid 3|object||
|`--plugin`|Plugin-specific configuration. Keys should correspond to plugin package names|object||
|`--plugins-import-chunk-size`|Maximum number of plugins that can be imported in parallel on server startup|number|`7`|
|`--port`, `-p`|Port to listen on|integer|`4723`|
|`--relaxed-security`|Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`.|boolean|`false`|
|`--session-override`|Enable session override (clobbering)|boolean|`false`|
|`--shutdown-timeout`|Timeout (in milliseconds) for waiting on all active connections to close, when shutting down the server|number|`5000`|
|`--ssl-cert-path`|Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details.|string||
|`--ssl-key-path`|Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details.|string||
|`--strict-caps`|Prevent creation of new client sessions that use unsupported capabilities|boolean|`false`|
|`--tmp`|Absolute path to the directory used for temporary files|string|[`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir)|
|`--use-drivers`|List of drivers to activate. By default, all installed drivers are activated.|array<string>|`[]`|
|`--use-plugins`|List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins.|array<string>|`[]`|
|`--webhook`, `-G`|URL for an HTTP listener where the server logs should be output. This does not affect output on the console.|string||
### Info Options
The following options are used for reference or debug purposes. They are only supported for the base `appium` command (not `appium server`), and will not launch the server.
|<div style="width:10em">Argument</div>|Description|
|--|--|
|`--show-build-info`|Print detailed information on the Appium server version|
|`--show-config`|Print the current Appium server configuration details|
|`--show-debug-info`|Print information on the current environment: details about the operating system, Node.js, and Appium itself|
|`--version`, `-v`|Print the Appium server version|

89
packages/appium/docs/en/reference/cli/setup.md
View File

@@ -1,33 +1,76 @@
---
hide:
- toc
title: Setup Command-Line Usage
title: appium setup
---
<style>
ul[data-md-component="toc"] .md-nav {
display: none;
}
</style>
The `setup` command aims to simplify the initial procedure of setting up Appium. It allows to install
multiple extensions (drivers/plugins) in one go, without the need to run
`appium <ext-name> install <ext-name>` multiple times.
Installs a specific preset of extensions (drivers and plugins), or uninstalls all extensions.
When installing a preset, any already installed extensions are kept intact.
The command has several presets that can be used to install different sets of extensions.
The presets are as follows:
|Preset|Installation Command|Included Drivers|Included Plugins|
|--|--|--|--|
|Mobile|`appium setup mobile` or `appium setup`|`uiautomator2`, `xcuitest`[^1], `espresso`|`images`|
|Desktop application|`appium setup desktop`|`mac2`[^1], `windows`[^2]|`images`|
|Desktop browser|`appium setup browser`|`safari`[^1], `gecko`, `chromium`|`images`|
Attempting to install a preset while already having one or more of its included extensions installed
will only install the missing extensions.
The following sub-subcommands are supported: `browser`, `desktop`, `mobile`, and `reset`.
Refer to the [Ecosystem documentation](../../ecosystem/index.md) to learn more about the extensions
listed above.
mentioned below.
This commands also supports the functionality that allows to fully reset your Appium server
deployment if you experience various configuration issues,
for example, due to a failed upgrade attempt from an older Appium version, on server startup.
By running `appium setup reset` the server would uninstall all installed drivers, plugins and their related manifest files from the currently used Appium home folder.
## `browser`
Installs the following extensions for browser webview testing:
* Drivers: `safari`[^1], `gecko`, `chromium`
* Plugins: `images`
#### Usage
```
appium setup browser
```
## `desktop`
Installs the following extensions for desktop application testing:
* Drivers: `mac2`[^1], `windows`[^2]
* Plugins: `images`
#### Usage
```
appium setup desktop
```
## `mobile`
Installs the following extensions for mobile testing:
* Drivers: `uiautomator2`, `xcuitest`[^1], `espresso`
* Plugins: `images`
#### Usage
```
appium setup mobile
```
You can also omit the `mobile` sub-subcommand:
```
appium setup
```
## `reset`
Uninstalls all installed extensions, along with their manifest files, from the Appium home
directory. This can be useful if you experience configuration issues on server startup, for
example, due to a failed upgrade attempt from an older Appium version.
#### Usage
```
appium setup reset
```
[^1]: Only installed if the host machine is running macOS.
[^2]: Only installed if the host machine is running Windows.

4
packages/appium/docs/mkdocs-en.yml
View File

@@ -38,10 +38,10 @@ nav:
- reference/index.md
- Command Line Interface:
- reference/cli/index.md
- reference/cli/args.md
- reference/cli/env-vars.md
- reference/cli/server.md
- reference/cli/extensions.md
- reference/cli/setup.md
- reference/cli/env-vars.md
- API Endpoints:
- reference/api/index.md
- reference/api/base-driver.md