npm package: @octomind/octomind
Description: a command line client for octomind apis
Author: octomind
Latest version: 4.7.0

# Octomind CLI

![Continuous Integration](https://github.com/octomind-dev/cli/actions/workflows/ts.yml/badge.svg)

A command-line interface for interacting with the Octomind API. 
This CLI allows you to execute tests, retrieve test reports, and manage private locations as well as environments.
See [API documentation](https://octomind.dev/docs/api-reference/)

<img src="assets/octomind-cli-opt.gif" />

## Usage / Installation

1. To install the package globally do **NOT** just a `npm i -g @octomind/octomind` but instead 
```bash
mkdir -p ~/.local/packages
cd ~/.local/packages
npm install @octomind/octomind@latest
# either create an alias
alias octomind="node ~/.local/packages/node_modules/@octomind/octomind/dist/index.js"
# or create a symlink
sudo ln -s ~/.local/packages/node_modules/@octomind/octomind/dist/index.js /usr/local/bin/octomind
```

this will install the package to `~/.local/packages` and create symlinks in `/usr/local/bin` or creates an alias. 
This is necessary for the cli to work and avoid dependency conflicts, when installing the package globally.

2. Use the cli through npx e.g. `npx @octomind/octomind -h`

## Autocompletion

On macOS and linux you can enable autocompletion by running the following command (works for bash, zsh & fish):
```bash
npx @octomind/octomind install-completion
```
You can disable autocompletion by running the following command:
```bash
npx @octomind/octomind uninstall-completion
```

Autocompletion will only work if you have installed the package globally and created a config file with `npx @octomind/octomind init`.
This way even entityIds like environmentIds or testCaseIds will be autocompleted.

# octomind

Octomind cli tool. Version: 4.7.0. Additional documentation see https://octomind.dev/docs/api-reference/

**Usage:** `octomind [options] [command]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-V, --version` | output the version number | No |  |

## Setup

## init

Initialize configuration by setting up API key. This will create a config file in ~/.config/octomind.json

**Usage:** `init [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-t, --test-target-id <id>` | Test target ID | Yes |  |
| `-k, --api-key <key>` | the api key for authentication | Yes |  |
| `-f, --force` | Force overwrite existing configuration | No |  |

## switch-test-target

Switch to a different test target. This will list all available test targets and update the config file in ~/.config/octomind.json

**Usage:** `switch-test-target [options]`

## Completion

## install-completion

Install tab completion

**Usage:** `install-completion [options]`

## uninstall-completion

Uninstall tab completion

**Usage:** `uninstall-completion [options]`

## completion

Tab completion

**Usage:** `completion [options]`

## Environments

## list-environments

List all environments

**Usage:** `list-environments [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## create-environment

Create a new environment

**Usage:** `create-environment [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-n, --name <name>` | Environment name | Yes |  |
| `-d, --discovery-url <url>` | Discovery URL | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `--test-account-username [username]` | Test account username | No |  |
| `--test-account-password [password]` | Test account password | No |  |
| `--test-account-otp-initializer-key [key]` | Test account OTP initializer key | No |  |
| `--basic-auth-username [username]` | Basic auth username | No |  |
| `--basic-auth-password [password]` | Basic auth password | No |  |
| `--private-location-name [name]` | Private location name | No |  |

## environment

Get an environment

**Usage:** `environment [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-e, --environment-id <id>` | Environment ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## update-environment

Update an existing environment

**Usage:** `update-environment [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-e, --environment-id <id>` | Environment ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-n, --name [name]` | Environment name | No |  |
| `-d, --discovery-url [url]` | Discovery URL | No |  |
| `--test-account-username [username]` | Test account username | No |  |
| `--test-account-password [password]` | Test account password | No |  |
| `--test-account-otp-initializer-key [key]` | Test account OTP initializer key | No |  |
| `--basic-auth-username [username]` | Basic auth username | No |  |
| `--basic-auth-password [password]` | Basic auth password | No |  |
| `--private-location-name [name]` | Private location name | No |  |

## delete-environment

Delete an environment

**Usage:** `delete-environment [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-e, --environment-id <id>` | Environment ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## Execute

## debug

run test cases against local build. can also be authenticated with a bearer token so no need to provide an api key

**Usage:** `debug [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-u, --url <url>` | url the tests should run against | Yes |  |
| `-c, --test-case-id [uuid]` | id of the test case you want to run, if not provided will run all test cases in the test target | No |  |
| `-e, --environment-id [uuid]` | id of the environment you want to run against, if not provided will run all test cases against the default environment | No |  |
| `-t, --test-target-id [uuid]` | id of the test target of the test case, if not provided will use the test target id from the config | No |  |
| `--headless` | if we should run headless without the UI of playwright and the browser | No |  |
| `--persist` | if we should write playwright config and files to current directory, you can then run 'npx playwright test' to run them again | No |  |
| `--grep [substring]` | filter test cases by substring | No |  |
| `--bypass-proxy` | bypass proxy when accessing the test target | No |  |
| `--browser [CHROMIUM, FIREFOX, SAFARI]` | Browser type | No | CHROMIUM |
| `--breakpoint [DESKTOP, MOBILE, TABLET]` | Breakpoint | No | DESKTOP |
| `--run-status [ON, OFF]` | only run test cases that are either ON or OFF | No |  |
| `-b, --bearer-token [token]` | Bearer token for authentication (instead of api key) | No |  |

## execute

Execute test cases to create a test report

**Usage:** `execute [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-u, --url <url>` | URL to test | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-e, --environment-name [name]` | Environment name | No | default |
| `-d, --description [text]` | Test description | No |  |
| `-g, --tags [tags]` | Comma separated list of tags | No |  |
| `-v, --variables-to-overwrite [variables]` | JSON object of variables to overwrite | No |  |
| `-b, --browser [type]` | Browser type [CHROMIUM, FIREFOX, SAFARI] | No | CHROMIUM |
| `-r, --breakpoint [name]` | Breakpoint [DESKTOP, MOBILE, TABLET] | No | DESKTOP |

## execute-local

Execute local YAML test cases

**Usage:** `execute-local [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-u, --url <url>` | Url the tests should run against | Yes |  |
| `-p, --test-case-path [string]` | Path of the test case you want to run, if not provided will run all test cases in the test target | No |  |
| `-e, --environment-id [uuid]` | Id of the environment you want to run against, if not provided will run all test cases against the default environment | No |  |
| `-t, --test-target-id [uuid]` | Id of the test target of the test case, if not provided will use the test target id from the config | No |  |
| `--headless` | If we should run headless without the UI of playwright and the browser | No |  |
| `--bypass-proxy` | Bypass proxy when accessing the test target | No |  |
| `--browser [CHROMIUM, FIREFOX, SAFARI]` | Browser type | No | CHROMIUM |
| `--breakpoint [DESKTOP, MOBILE, TABLET]` | Breakpoint | No | DESKTOP |

## create-discovery

Create a new test case discovery

**Usage:** `create-discovery [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-n, --name <name>` | Discovery name | Yes |  |
| `-p, --prompt <prompt>` | Discovery prompt | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-e, --entry-point-url-path [path]` | Entry point URL path | No |  |
| `--prerequisite-id [id]` | Prerequisite test case ID | No |  |
| `--external-id [id]` | External identifier | No |  |
| `--assigned-tag-ids [ids]` | Comma-separated list of tag IDs | No |  |
| `--folder-id [id]` | Folder ID | No |  |

## batch-generation

Batch generation of test cases

**Usage:** `batch-generation [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-p, --prompt <prompt>` | Batch generation prompt | Yes |  |
| `-u, --url <url>` | Start url for generation | Yes |  |
| `-e, --environment-id <id>` | Environment ID | Yes |  |
| `-d, --prerequisite-id <id>` | Prerequisite ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## Notifications

## notifications

Get notifications for a test target

**Usage:** `notifications [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## Private Locations

## register-location

Register a private location

**Usage:** `register-location [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-n, --name <name>` | Location name | Yes |  |
| `-p, --password <password>` | Proxy password | Yes |  |
| `-u, --username <user>` | Proxy user | Yes |  |
| `-a, --address <address>` | Location address | Yes |  |

## unregister-location

Unregister a private location

**Usage:** `unregister-location [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-n, --name <name>` | Location name | Yes |  |

## list-private-locations

List all private locations

**Usage:** `list-private-locations [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |

## start-private-location

Start a private location worker, see https://octomind.dev/docs/proxy/private-location

**Usage:** `start-private-location [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-n, --name [name]` | Location name | No |  |
| `-u, --username [username]` | Proxy user | No |  |
| `-p, --password [password]` | Proxy password | No |  |
| `-l, --host-network` | Use host network (default: false). If set you can use localhost directly | No | false |

## stop-private-location

Stop a private location worker, see https://octomind.dev/docs/proxy/private-location

**Usage:** `stop-private-location [options]`

## Test Cases

## delete-test-case

Delete a test case

**Usage:** `delete-test-case [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-c, --test-case-id <id>` | Test case ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## code

Get code of a specific test case

**Usage:** `code [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-c, --test-case-id <id>` | Test case ID | Yes |  |
| `-u, --url <url>` | URL to execute the test case against | Yes |  |
| `-e, --environment-id [id]` | Environment ID | No | default |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## test-case

Get details of a specific test case

**Usage:** `test-case [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-c, --test-case-id <id>` | Test case ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## list-test-cases

List all test cases

**Usage:** `list-test-cases [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## pull

Pull test cases from the test target

**Usage:** `pull [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-p, --test-plan-id [id]` | Optional test plan ID to filter test cases | No |  |
| `-r, --test-report-id [id]` | Optional test report ID to only pull test case auto-fixes from a specific test report | No |  |

## push

Push local YAML test cases to the test target

**Usage:** `push [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-y, --yes` | Skip confirmation prompt | No |  |

## create-test-case

Create a new test case

**Usage:** `create-test-case [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |
| `-n, --name <string>` | The name of the test case you want to create | Yes |  |
| `-d, --dependency-path [path]` | The path of to test case you want to use as dependency | No |  |

## edit-test-case

Edit yaml test case

**Usage:** `edit-test-case [options] <file-path>`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## Test Reports

## test-report

Get test report details

**Usage:** `test-report [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |
| `-r, --test-report-id <id>` | Test report ID | Yes |  |
| `-t, --test-target-id [id]` | Test target ID, if not provided will use the test target id from the config | No |  |

## Test Targets

## list-test-targets

List all test targets

**Usage:** `list-test-targets [options]`

### Options

| Option | Description | Required | Default |
|:-------|:----------|:---------|:--------|
| `-j, --json` | Output raw JSON response | No |  |

## Update

## update

update your local cli version

**Usage:** `update [options]`



## Output Formats

By default, the CLI provides formatted text output for better readability. Add the `--json` flag to any command to get the raw JSON response instead. This is useful for scripting or when you need to process the output programmatically.

Example of JSON output:
```json
{
  "id": "826c15af-644b-4b28-89b4-f50ff34e46b7",
  "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
  "status": "PASSED",
  "executionUrl": "https://example.com",
  "testResults": [
    {
      "id": "abc-123-456",
      "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
      "testCaseId": "test-1",
      "status": "PASSED",
      "traceUrl": "https://storage.googleapis.com/automagically-traces/abc-123-trace.zip"
    },
    {
      "id": "def-456-789",
      "testTargetId": "3435918b-3d29-4ebd-8c68-9a540532f45a",
      "testCaseId": "test-2",
      "status": "PASSED",
      "traceUrl": "https://storage.googleapis.com/automagically-traces/def-456-trace.zip"
    }
  ]
}
```

## Development

1. Clone the repository
2. Install dependencies:
```bash
pnpm install
```

The CLI is written in TypeScript and uses the following dependencies:
- [commander](https://github.com/tj/commander.js): For command-line argument parsing
- [openapi-fetch](https://openapi-ts.dev/openapi-fetch/): For making openapi API calls
- [openapi-typescript](https://openapi-ts.dev/introduction): For generating types from openapi spec

To build from source:
```bash
pnpm run build
```