> For the complete documentation index, see [llms.txt](https://docs.panther.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.panther.com/~/changes/2402/detections/pypanther/cli.md).

# Using the pypanther Command Line Tool

View, test, and upload V2 detections

## Overview

{% hint style="info" %}
The `pypanther` CLI tool is in closed beta starting with Panther version 1.108. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}

Use the `pypanther` command line interface (CLI) tool to:

* View, test, and upload PyPanther Detections. 
* [Convert](#using-convert) v1 detections to PyPanther Detections.
* View and [upload schemas](#uploading-schemas-to-panther).

To get started using `pypanther`, follow the instructions in the [pypanther-starter-kit's README](https://github.com/panther-labs/pypanther-starter-kit/blob/main/README.md). See the [list of available CLI commands](#pypanther-cli-command-reference) below, and note that some require [authentication](#authenticating-cli-commands).

## `pypanther` CLI command reference

{% hint style="info" %}
Find out more about each command by passing the `--help` argument (or `-h`).
{% endhint %}

<table><thead><tr><th width="131">Command</th><th width="423">How it works</th><th width="234">Required API permission(s)</th></tr></thead><tbody><tr><td><code>list</code></td><td>Lists locally defined detections and schemas.</td><td>None</td></tr><tr><td><code>get</code></td><td>Gets the attributes of locally defined detections and schemas.</td><td>None</td></tr><tr><td><code>test</code></td><td><p>Runs detection tests locally.<br></p><p>Learn more in <a href="/~/changes/2402/detections/pypanther.md#running-tests">Running tests</a>.</p></td><td>None</td></tr><tr><td><code>upload</code></td><td><p>Uploads local detections and schemas to Panther. </p><p></p><p>Learn more in <a href="/~/changes/2402/detections/pypanther.md#uploading-pypanther-detections-to-panther">Uploading PyPanther Detections to Panther</a> and <a href="#uploading-schemas-to-panther">Uploading schemas to Panther</a></p><p></p><p>The default schemas path is <code>content/schemas</code><br><br>Warning: In order to use the <code>pypanther</code> <code>upload</code> functionality, it must first be enabled for you. If you would like to upload detections, please reach out to your Panther Support team.</p></td><td><ul><li>Bulk Upload</li><li>Manage Log Sources (if <a href="#uploading-schemas-to-panther">uploading schemas</a>) </li></ul></td></tr><tr><td><code>convert</code></td><td>Converts <a href="/pages/fuevggJbZJLu23hzikkW#pypanther-detections-vs.-v1-detections">v1</a> rules and helpers into PyPanther format. Learn more in <a href="#using-convert">Using <code>convert</code></a>, below.</td><td>None</td></tr></tbody></table>

## Authenticating CLI commands

Certain `pypanther` CLI commands, like `upload`, require authentication with your Panther instance. This means they require a valid Panther API host URL and API token. After you locate/generate these values, you will make them visible to `pypanther`.

### Step 1: Locate/generate your Panther API host URL and token

* **Panther API host URL**: Follow [these instructions to locate your GraphQL API URL](/~/changes/2402/panther-developer-workflows/api/graphql.md#step-1-identify-your-panther-graphql-api-url).
* **Panther API token**: Follow [these instructions to generate an API token](/~/changes/2402/panther-developer-workflows/api.md#how-to-create-a-panther-api-token), being sure to attach any permissions required by the `pypanther` commands you'd like to use. See the **Required API permission(s)** column in the table above.

### Step 2: Make API host and token values visible to `pypanther`

Once you have API host and token values, you can choose how to expose them to `pypanther` when you are executing a CLI command. The following methods are in order of precedence, meaning option one overrides option two:

1. Pass the host and token on the command line using `--api-token` and `--api-host`.
2. Set the host and token as environment variables using `PANTHER_API_TOKEN` and `PANTHER_API_HOST`.

## Uploading schemas to Panther

In addition to using `pypanther upload` to upload PyPanther Detections to Panther, you can also upload custom data schemas (used for [custom log types](/~/changes/2402/data-onboarding/custom-log-types.md) and [Lookup Tables](/~/changes/2402/enrichment/lookup-tables.md)). When you run the `upload` command, `pypanther` looks in `/content/schemas` for schemas to upload.

`pypanther` supports uploading YAML schemas defined according to the [How to define a custom schema](/~/changes/2402/data-onboarding/custom-log-types.md#how-to-define-a-custom-schema) instructions.

## Using `convert`

The `pypanther` `convert` command converts [v1](https://docs.panther.com/~/changes/2402/detections/pypanther/pages/fuevggJbZJLu23hzikkW#pypanther-detections-vs.-v1-detections) rules and helpers into PyPanther format.

{% hint style="info" %}
The `convert` command does not output a `main.py` file. You must create this yourself. Learn more about what to include in [`main.py` content recommendations](https://docs.panther.com/~/changes/2402/detections/pypanther/pages/QznvPdDzlJEzG7eOvYlj#main.py-content-recommendations).
{% endhint %}

When converting a v1 rule, `convert` first checks whether it is custom or Panther-managed (by looking at its `RuleId`). If it's a custom rule, `convert` creates a straightforward translation of the rule.&#x20;

If it's a Panther-managed rule, `convert` attempts to make as minimal of an override as possible. This means:

* If there have only been modifications to the Panther-managed rule's attributes (i.e., the fields stored in the YAML file in v1), and not to its [alert functions](/~/changes/2402/detections/rules/python.md#alert-functions-in-python-detections), the Panther-managed rule is [overridden](/~/changes/2402/detections/pypanther.md#applying-overrides-on-existing-rules) using `override` to make the same customization(s) in PyPanther.
  * The overrides are made in an `apply_overrides` function inside a log type-specific file that is stored in an `overrides` directory.
* If there have been modifications made to any of the Panther-managed rule's [alert functions](/~/changes/2402/detections/rules/python.md#alert-functions-in-python-detections), a rule is created that [subclasses](/~/changes/2402/detections/pypanther.md#creating-pypanther-rules-with-inheritance) the Panther-managed rule. The subclassed rule defines all alert functions that were modified in v1 (in addition to any modified attributes).
  * The subclassed rule is created in a new file inside the `rules` directory.


---

# 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.panther.com/~/changes/2402/detections/pypanther/cli.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.