# `nimbus-cli`

Mozilla Nimbus' command line tool for mobile apps.

Currently supporting testing on device or emulator for Android, and on simulator only for iOS.

This provides a unified interface for QA and developers to enroll and unenroll into experiments,
including first run experiments.

## Supported apps

The apps currently supported are:

- Firefox for Android (`fenix`)
- Firefox for iOS (`firefox_ios`)
- Focus for Android (`focus_android`)
- Focus for iOS (`focus_ios`).

## Usage

```sh
Usage: nimbus-cli [OPTIONS] <COMMAND>

Commands:
  apply-file    Send a complete JSON file to the Nimbus SDK and apply it immediately
  capture-logs  Capture the logs into a file
  defaults      Print the defaults for the manifest
  enroll        Enroll into an experiment or a rollout
  features      Print the feature configuration involved in the branch of an experiment
  fetch         Fetch one or more named experiments and rollouts and put them in a file
  fetch-list    Fetch a list of experiments and put it in a file
  info          Displays information about an experiment
  jexl          Evaluate a JEXL expression against the app context
  list          List the experiments from a server
  log-state     Print the state of the Nimbus database to logs
  open          Open the app without changing the state of experiment enrollments
  start-server  Start a server
  reset-app     Reset the app back to its just installed state
  tail-logs     Follow the logs for the given app
  test-feature  Configure an application feature with one or more feature config files
  unenroll      Unenroll from all experiments and rollouts
  validate      Validate an experiment against a feature manifest
  help          Print this message or the help of the given subcommand(s)

Options:
  -a, --app <APP>              The app name according to Nimbus
  -c, --channel <CHANNEL>      The channel according to Nimbus. This determines which app to talk to
  -d, --device-id <DEVICE_ID>  The device id of the simulator, emulator or device
  -h, --help                   Print help (see more with '--help')
```

### Enroll

```sh
Enroll into an experiment or a rollout.

The experiment slug is a combination of the actual slug, and the server it came from.

* `release`/`stage` determines the server.

* `preview` selects the preview collection.

These can be further combined: e.g. $slug, preview/$slug, stage/$slug, stage/preview/$slug

Usage: nimbus-cli --app <APP> --channel <CHANNEL> enroll [OPTIONS] --branch <BRANCH> <EXPERIMENT_SLUG> [ROLLOUTS]... [-- <PASSTHROUGH_ARGS>...]

Arguments:
  <EXPERIMENT_SLUG>
          The experiment slug, including the server and collection

  [ROLLOUTS]...
          Optional rollout slugs, including the server and collection

  [PASSTHROUGH_ARGS]...
          Optionally, add platform specific arguments to the adb or xcrun command.

          By default, arguments are added to the end of the command, likely to be passed directly to the app.

          Arguments before a special placeholder `{}` are passed to `adb am start` or `xcrun simctl launch` commands directly.

Options:
      --file <EXPERIMENTS_FILE>
          An optional file from which to get the experiment.

          By default, the file is fetched from the server.

      --use-rs
          Use remote settings to fetch the experiment recipe.

          By default, the file is fetched from the v6 api of experimenter.

      --patch <PATCH_FILE>
          An optional patch file, used to patch feature configurations

          This is of the format that comes from the `features --multi` or `defaults` commands.

  -b, --branch <BRANCH>
          The branch slug

      --preserve-targeting
          Preserves the original experiment targeting

      --preserve-bucketing
          Preserves the original experiment bucketing

      --deeplink <DEEPLINK>
          Optional deeplink. If present, launch with this link

      --reset-app
          Resets the app back to its initial state before launching

      --preserve-nimbus-db
          Keeps existing enrollments and experiments before enrolling.

          This is unlikely what you want to do.

      --no-validate
          Don't validate the feature config files before enrolling

      --manifest <MANIFEST_FILE>
          An optional manifest file

      --version <APP_VERSION>
          An optional version of the app. If present, constructs the `ref` from an app specific template. Due to inconsistencies in branching names, this isn't always reliable

      --ref <APP_VERSION>
          The branch/tag/commit for the version of the manifest to get from Github

          [default: main]

  -h, --help
          Print help (see a summary with '-h')
```

### List

```sh
List the experiments from a server

Usage: nimbus-cli --app <APP> --channel <CHANNEL> list [OPTIONS] [SERVER]

Arguments:
  [SERVER]
          A server slug e.g. preview, release, stage, stage/preview

          [default: ]

Options:
  -f, --file <FILE>
          An optional file

      --use-api
          Use the v6 API to fetch the experiment recipes.

          By default, the file is fetched from the Remote Settings.

          The API contains *all* launched experiments, past and present, so this is considerably slower and longer than Remote Settings.

  -h, --help
          Print help (see a summary with '-h')
```

### Test Feature

```sh
Configure an application feature with one or more feature config files.

One file per branch. The branch slugs will correspond to the file names.

By default, the files are validated against the manifest; this can be overridden with `--no-validate`.

Usage: nimbus-cli --app <APP> --channel <CHANNEL> test-feature [OPTIONS] <FEATURE_ID> [FILES]... [-- <PASSTHROUGH_ARGS>...]

Arguments:
  <FEATURE_ID>
          The identifier of the feature to configure

  [FILES]...
          One or more files containing a feature config for the feature

  [PASSTHROUGH_ARGS]...
          Optionally, add platform specific arguments to the adb or xcrun command.

          By default, arguments are added to the end of the command, likely to be passed directly to the app.

          Arguments before a special placeholder `{}` are passed to `adb am start` or `xcrun simctl launch` commands directly.

Options:
      --patch <PATCH_FILE>
          An optional patch file, used to patch feature configurations

          This is of the format that comes from the `features --multi` or `defaults` commands.

      --deeplink <DEEPLINK>
          Optional deeplink. If present, launch with this link

      --reset-app
          Resets the app back to its initial state before launching

      --no-validate
          Don't validate the feature config files before enrolling

      --manifest <MANIFEST_FILE>
          An optional manifest file

      --version <APP_VERSION>
          An optional version of the app. If present, constructs the `ref` from an app specific template. Due to inconsistencies in branching names, this isn't always reliable

      --ref <APP_VERSION>
          The branch/tag/commit for the version of the manifest to get from Github

          [default: main]

  -h, --help
          Print help (see a summary with '-h')
```

### eval-jexl

```sh
Evaluate a JEXL expression against the app context.

This command is useful for testing and debugging JEXL targeting expressions.
The app will evaluate the expression and return the result as JSON.

Usage: nimbus-cli --app <APP> --channel <CHANNEL> eval-jexl <EXPRESSION> [OPTIONS]

Arguments:
  <EXPRESSION>
          The JEXL expression to evaluate (e.g. "locale == 'en-US'")

Options:
      --deeplink <DEEPLINK>
          Optional deeplink. If present, launch with this link

      --pbcopy
          Copy the deeplink URL to clipboard instead of launching

      --pbpaste
          Use the deeplink URL from clipboard

      --output <OUTPUT>
          Write the deeplink URL to a file

  -h, --help
          Print help (see a summary with '-h')
```

**Example:**
```sh
# Evaluate a simple expression
nimbus-cli --app fenix --channel developer eval-jexl "locale == 'en-US'"

# Test version comparison
nimbus-cli --app firefox_ios --channel beta eval-jexl "app_version|versionCompare('120.0') >= 0"

# Copy deeplink to clipboard for manual testing
nimbus-cli --app fenix --channel developer eval-jexl "is_default_browser" --pbcopy
```

## Environment Variables

- `XCRUN_PATH` the path to `xcrun`. This is only useful with macOS.
- `ADB_PATH` the path to `adb`.
- `NIMBUS_URL` the URL to the RemoteSettings server; a default is supplied.
- `NIMBUS_URL_STAGE` the URL to the staging RemoteSettings server; a default is supplied.
- `NIMBUS_V6_URL` the host for the Experimenter, used as a basis for the calls to `/api/v6`; a default is supplied.
- `NIMBUS_V6_URL_STAGE` the host for the staging Experimenter, used as a basis for the calls to `/api/v6`; a default is supplied.
- `NIMBUS_MANIFEST_CACHE` the directory where remote Feature Manifests are cached. A temp directory is used as default.
- `NIMBUS_CLI_SERVER_HOST` the IP address the server is on; defaults to the local IP address derived from the network interface.
- `NIMBUS_CLI_SERVER_PORT` the port the server is on; defaults to 8080.