> For the complete documentation index, see [llms.txt](https://docs.oxygenhq.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oxygenhq.org/download-installation-start/start-working-with-oxygen/introduction-and-usage.md).

# Getting Started- Oxyge CLI

## Oxygen CLI

For Oxygen-CLI download instructions - please refer to the [Download Page](https://docs.oxygenhq.org/download-installation-start/download-and-installation/cli-installation).

## Introduction <a href="#introduction" id="introduction"></a>

Oxygen CLI is a command-line application for running test cases and test suites. It's intended mainly for integration with CI and build systems, but can be used as well for running scripts manually from the command-line. The results are produced as a set of XML/HTML/Excel/JSON/PDF reports plus the screenshots in case of test failures.

## Usage <a href="#usage" id="usage"></a>

```bash
oxygen [OPTIONS]... FILE
```

Oxygen CLI can execute two types of files - test scripts (refered to as test cases) and test suites. Test suite allows defining and running collection of test cases.

Example of test suite for desktop web applications (Selenium):

```javascript
{
  "iterations": 2,
  "parallel": 1,
  "url": "http://localhost:4444/wd/hub",
  "cases": [
    {
      "name": "case1",
      "path": "./testcase1.js"
    },
    {
      "name": "case2",
      "path": "./testcase2.js"
    }
  ],
  "environment": {
    "some_parameter": "foo",
    "another_parameter": "bar"
  },
  "capabilities": [
    {
      "browserName": "ie"
    },
    {
      "browserName": "chrome"
    }
  ],
  "options": {
    "autoReopen": true
  }
}
```

Example of test suite for mobile applications (Appium):

```javascript
{
  "iterations": 2,
  "parallel": 1,
  "server": {
    "host": "localhost",
    "port": 4723
  },
  "cases": [
    {
      "name": "case1",
      "path": "./testcase1.js"
    },
    {
      "name": "case2",
      "path": "./testcase2.js"
    }
  ],
  "environment": {
    "some_parameter": "foo",
    "another_parameter": "bar"
  },
  "capabilities": [
    {
      "platformName": "Android",
      "platformVersion": "4.2",
      "deviceName": "90a92348",
      "appPackage": "com.sec.android.app.popupcalculator",
      "appActivity": "com.sec.android.app.popupcalculator.Calculator"
    },
    {
      "platformName": "Android",
      "platformVersion": "5.0",
      "deviceName": "ef4718a9",
      "appPackage": "com.sec.android.app.popupcalculator",
      "appActivity": "com.sec.android.app.popupcalculator.Calculator"
    }
  ]
}
```

**General Options**

* ```bash
  --rf={html|xml|excel|pdf|junit|json}
  ```

  Format of the test reports. Default is html.\
  Reports will be generated in the same directory where test script is located.
* ```bash
  --ro=PATH
  ```

  Output path for the report file. If specified, the report file will be simply generated in the specified directory and will overwrite any previous reports. If omitted, then report will be generated using date-time folder structure. This is the default behavior.
* ```bash
  -i, --iter=COUNT
  ```

  Number of times (iterations) to run the test. Default is 1.
* ```bash
  -p, --param=FILE
  ```

  Parameters file. If not specified an attempt will be made to load parameters from a file named same as the test script, located in the same directory, and having extension - xlsx, xls, csv, or txt.
* ```bash
  --pm={seq|random|all}
  ```

  Order in which to read the parameters - sequential, random, all. Default is `seq`. In `seq` and `random` modes test will run exact number of times specified with the `-i` option. In `all` mode, all available parameters will be read sequentially. This option is mutually exclusive with `-i` option.

**Options for Web test**

* ```bash
  -b, --browser={chrome|ie|firefox|safari}
  ```

  Browser name. Default is chrome.
* ```bash
  -s, --server=SERVER_URL
  ```

  Selenium hub URL. Default is <http://localhost:4444/wd/hub>.
* ```bash
  --reopen={true|false}
  ```

  Reopen browser on each iteration. Default is false.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oxygenhq.org/download-installation-start/start-working-with-oxygen/introduction-and-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.