# NetoFuse CLI

## Using the CLI <a href="#using-the-cli" id="using-the-cli"></a>

`netofuse` is a shell script that constructs a `docker run` command to execute commands in the container image if you are using the container deployment and have run the Docker host setup script.

`netofuse` is the Python code directly running on your local system if you installed the Python package.

The commands work in the same way regardless of which deployment option you used. Remember that if you are using the container, all file paths refer to the path inside the container, not on your Docker host.

## Commands <a href="#commands" id="commands"></a>

### `run` <a href="#run" id="run"></a>

Usage: `netofuse run [module]`

Executes integration with the name specified and exits.

### `upload` <a href="#upload" id="upload"></a>

Usage: `netofuse upload [--transform FILE] [--neto API] [--use-labels] filename`

Upload context labels to Netography Fusion in a supported file format (CSV or JSON) from a local file.

There are two different formats for CSV files that are supported for upload:

#### Upload a Generic CSV <a href="#upload-a-generic-csv" id="upload-a-generic-csv"></a>

The `upload` command by default expects generic output in `csv` format that will then have field names converted with the transform file specified.

{% hint style="info" %}
**📘When to use a generic CSV format**

This is useful if you have another application that is saving a CSV file to disk, as `netofuse` can handle transforming the names and values of the CSV with the transform, converting it to the Netography labels format, and upload it via API, handling all the cases of proper formatting, characters, and pagination for you.

It is also useful if you want to use a module to download the CSV file and then later upload it in a separate step to Netography. You might do this if you wanted to inspect or do post-processing on the CSV file before you upload context labels to Netograpy.
{% endhint %}

1. Create a transform file based on the headers using the [buildtransform command](#buildtransform) with the `-csv filename` option.
2. Edit the transform file to create the desired field mappings. Consult [Context Transforms](/netofuse/context-transforms.md) for more details on this step.
3. Add the `--transform filename` option to the upload command to use this field mapping.

**Example for generic CSV upload**

`mydata.csv`

```
NAME,LOCATION,IP
myhost,Annapolis,10.0.0.1
yourhost,Atlanta,10.8.0.1
```

{% tabs %}
{% tab title="Shell" %}

```
netofuse buildtransform --csv mydata.csv mydata.transform
nano mydata.transform  # or your preferred text/YAML editor
netofuse upload --transform mydata.transform mydata.csv
```

{% endtab %}
{% endtabs %}

**Directory to use with Docker**

The default docker run script sets the working directory within the docker container to `/app/netofuse/data` and maps that to `/var/netofuse` on the Docker host. Place the CSV file in `/var/netofuse` and edit the transform in that directory, as netofuse within the container will not be able to access or write files in your local working directory.

#### Upload a Netography formatted context label CSV file <a href="#upload-a-netography-formatted-context-label-csv-file" id="upload-a-netography-formatted-context-label-csv-file"></a>

If the CSV file is already formatted as the Netography context labels API expects, it can be directly uploaded without any transform or further processing. This is also the format exported when you set`labels: csv` in the `save:`section of a module configuration file.

{% hint style="info" %}
**📘Netography context labels CSV format**

The format of a labels CSV file is a file with **no** header row, with each row in the format of:

```
IP address, context name, value1, [value2], [value3], ...
```

The file should never have more than 1 row with the same IP address and context name. Instead, those values should all be appended to the single row. The values in a single row should never be duplicated.
{% endhint %}

To upload a CSV file in this format, add the `--use-labels`argument.

#### required argument: `filename` <a href="#required-argument-filename" id="required-argument-filename"></a>

The file(s) to import - can specify as a full path, directory, or use wildcards

#### optional argument: `[--transform FILE]` <a href="#optional-argument---transform-file" id="optional-argument---transform-file"></a>

Transform file to use (default: netofuse.upload.transform).

#### optional argument: `[--neto API]` <a href="#optional-argument---neto-api" id="optional-argument---neto-api"></a>

Netography API to use (only needed if multiple APIs configured). This should be the name of the API section in the configuration file.

#### optional argument: `[--use-labels]` <a href="#optional-argument---use-labels" id="optional-argument---use-labels"></a>

If this option is set, the file specified must be in the Netography context label file format. This is the same format that is output when the `labels` key is set in the`save:` section of the configuration. If this is not set, the file is transformed and converted to Netography context labels before uploading.

### `auth` <a href="#auth" id="auth"></a>

Usage: `netofuse auth [module/api]`

Attempt to authenticate to API endpoints

Use this to test if the API configuration parameters and credentials you have set for the Netography API and the modules you have configured are successfully authenticating.

### `verify` <a href="#verify" id="verify"></a>

Usage: `netofuse verify [module]`

Verify that the module is properly configured, authentication is working, and that asset information is being successfully retrieved. Testing any new or changed configurations for a module with this command is good practice. Verify will not upload any context labels to Netography Fusion, even if `upload:true` is set or `-u` is used.

#### optional argument: `[module]` <a href="#optional-argument-module" id="optional-argument-module"></a>

If specified, the module will be tested.\
If not specified, only the Netography API will be verified.

### `clear` <a href="#clear" id="clear"></a>

Usage: `clear [module]`

Clears the cache (including both any asset data and authentication tokens)

#### optional argument: `[module]` <a href="#optional-argument-module-1" id="optional-argument-module-1"></a>

If specified, only asset data from this module instance will be cleared.\
If not specified, all asset data will be cleared.

### `init` <a href="#init" id="init"></a>

Usage: `init [--force] [--envfile][filename]`

Initializes a new default configuration file and saves it as a file.

#### optional argument: `[--force]` <a href="#optional-argument---force" id="optional-argument---force"></a>

If this option is set, an existing configuration file will be overwritten if it exists.

#### optional argument:`[--envfile]` <a href="#optional-argument--envfile" id="optional-argument--envfile"></a>

If specified, the configuration will be written to an environment file instead of a yml file.

#### optional argument:`[filename]` <a href="#optional-argumentfilename" id="optional-argumentfilename"></a>

If specified, write the default configuration to this file.\
If not specified, `netofuse.yml` in the current directory is used by default, unless `--envfile` is also set, in which case `.netofuse.env` is used by default.\
Configuration is written to the current directory, unless a full path is specified, or the `--dir` command line option has set a new directory.

### `buildtransform` <a href="#buildtransform" id="buildtransform"></a>

Usage: `buildtransform [--force] [--csv filename] [module] [filename]`

Builds a new transform configuration by running an existing module or reading from a local CSV file. This is useful if you have configured a module to gather a new set of fields, as this will run the module to identify what fields are being returned, gather an example of values that can be used, and then create the structure for the transform that you can then modify to map fields and modify values. For more details on how transforms work, see [Context Transforms](/netofuse/context-transforms.md).

#### optional argument: `[--force]` <a href="#optional-argument---force-1" id="optional-argument---force-1"></a>

If this option is set, force overwriting an existing transform configuration, even if it already exists.

#### optional argument: `[--csv filename]` <a href="#optional-argument---csv-filename" id="optional-argument---csv-filename"></a>

If this option is set and filename is specified, a CSV file (with a header row) will be read and used to build the transform configuration.

#### required argument: `[module]` <a href="#required-argument-module" id="required-argument-module"></a>

The name of the module instance to run to build a transform for. This must be specified unless the --csv option is used.

#### optional argument: `[filename]` <a href="#optional-argument-filename" id="optional-argument-filename"></a>

The name of the file to write the transform configuration that is built by this command. If not specified, it will write to `transform.yml`by default.

### `api` <a href="#api" id="api"></a>

Usage: `api [--file filename] [--neto api] [--bytes N] method command [params *]`

You can directly interact with the Netography Fusion API from the NetoFuse command line with the `api` command. See [API Reference](https://docs.netography.com/api-reference) for more details of what is available in the API. Not all API calls are compatible with this command currently, but many are.

#### required argument: `method` <a href="#required-argument-method" id="required-argument-method"></a>

HTTP method to use in making API call (default: GET)

#### required argument: `command` <a href="#required-argument-command" id="required-argument-command"></a>

API command to execute (eg `labels/ips/10.1.1.1`)

#### optional argument: `[params *]` <a href="#optional-argument-params" id="optional-argument-params"></a>

List of parameters to set when making this cal (format is `key=value`)

#### optional argument: `[--file filename]` <a href="#optional-argument---file-filename" id="optional-argument---file-filename"></a>

Write the API response to a file (default is to STDOUT)

#### optional argument: `[--neto api]` <a href="#optional-argument---neto-api-1" id="optional-argument---neto-api-1"></a>

Netography API to use (only needed if multiple APIs configured). This should be the name of the API section in the configuration file (`api1` by default)

#### optional argument: `[--bytes N]` <a href="#optional-argument---bytes-n" id="optional-argument---bytes-n"></a>

Number of bytes to display from the API response (default: all)

### `delete-labels` <a href="#delete-labels" id="delete-labels"></a>

Usage: `delete-labels api`

Delete all context labels from the Netography Fusion API instance specified.

#### required argument: `api` <a href="#required-argument-api" id="required-argument-api"></a>

This can be useful if you have been testing a new module and need to reset the labels available in your account. Although most context labels are built using integrations that will automatically repopulate them, use caution deleting labels from your account if you have manually imported labels or have other context labels that are being used actively in production.

### additional commands <a href="#additional-commands" id="additional-commands"></a>

There are additional commands that may be listed by using the `--help` command. These may be infrequently used or to be deprecated commands. Use caution when running commands that are not fully documented, and contact Netography Support if you have any questions.

## Command Line Options <a href="#command-line-options" id="command-line-options"></a>

### `-h, --help` <a href="#h-help" id="h-help"></a>

Provides command line usage help

### `-c FILE, --config FILE` <a href="#c-file-config-file" id="c-file-config-file"></a>

Specifies the location of the YAML configuration file to be used. By default, it uses `netofuse.yml` in the current directory if this is not set.

### `-e FILE, --env FILE` <a href="#e-file-env-file" id="e-file-env-file"></a>

Specifies the location of the environment file to be used. By default, it uses `.netofuse.env` in the current directory if this is not set.

### `-d DIRECTORY, --dir DIRECTORY` <a href="#d-directory-dir-directory" id="d-directory-dir-directory"></a>

Specifies the working directory netofuse uses to read and write files from. Full pathnames specified will take precedence over the working directory for any files used.

### `-r, --resetcache` <a href="#r-resetcache" id="r-resetcache"></a>

Clears the cache before executing a command.

### `-n, --nocache` <a href="#n-nocache" id="n-nocache"></a>

Disables caching. This overrides any configuration file settings.

### `-u, --upload` <a href="#u-upload" id="u-upload"></a>

Enables uploading of labels to the configured Netography API with the command. This overrides `upload: false` being set in configuration.

### `-x, --noupload` <a href="#x-noupload" id="x-noupload"></a>

Disables uploading of labels. This overrides `upload: true` being set in configuration.

### `-l LEVEL, --level LEVEL` <a href="#l-level-level-level" id="l-level-level-level"></a>

Sets the logging level. Available logging levels are INFO, VERBOSE, WARNING, ERROR, DEBUG, TRACE.

### `-t FILE, --allow-custom-transforms FILE` <a href="#t-file-allow-custom-transforms-file" id="t-file-allow-custom-transforms-file"></a>

Enables custom transform functions in the specified Python file. See [Context Transforms](/netofuse/context-transforms.md) for more details on how to use this option.

### `-v, --version` <a href="#v-version" id="v-version"></a>

Prints the NetoFuse version and exits.


---

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

```
GET https://docs.fusion.vectra.ai/netofuse/shell-commands.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.