# Butler API Guide

The Replica Butler subsystem controls secure bi-directional transmission of all data flow in and out of Replica's Virtual Environments. Replica Butler APIs can be accessed in two contexts:

* External to Replica, to transfer files to and from external systems
* Within a Replica Environment, to move files within Replica, or access files which have been previously uploaded

You can script interactions with Replica Butler using Python. The required package is preinstalled in Linux environments and includes built-in docstrings for inline reference and IDE auto-completion. The Python package README.md additionally lists all available function samples.

## Using the API Within an Environment

The scripts below are available in Linux environments and helpful for automating tasks.

### Python Examples

Use the preinstalled Python package to interact with Butler from within a Replica environment.

<details open>

<summary>Use Butler Python package in Environment</summary>

**4.4.0**

```python
import sys
sys.path.append('/opt/greymarketlabs/configs/butler')

from butler import ReplicaButler

replicaButler = ReplicaButler()
initialized = replicaButler.initialize()

if initialized:
    response = replicaButler.ping()
    print(f'Ping response: {response}')

```

**4.5.0**

```python
from replica.butler import ReplicaButler

replicaButler = ReplicaButler()
initialized = replicaButler.initialize()

if initialized:
    response = replicaButler.ping()
    print(f'Ping response: {response}')
```

```sh
python3 my-script.py
```

</details>

***

## Using the API Externally to Replica

Use the Python package to interact with Butler from systems outside of Replica.

<details open>

<summary>Install Package</summary>

This will install the Replica Butler Python Wheel with `--no-deps` flag and into the current working directory via the `--target` flag.

{% hint style="info" %}
The code samples presume the Python Requests library is preinstalled in your system, Python venv or equivalent
{% endhint %}

```sh
pip3 install replica_butler-4.4.0-py3-none-any.whl --no-deps --target .
```

</details>

<details open>

<summary>Configure Credentials</summary>

Provide your instance domain name and credentials

| Environment Variable | Required | Description                                                     |
| -------------------- | -------- | --------------------------------------------------------------- |
| REPLICA\_DOMAIN      | Yes      | Replica domain name                                             |
| REPLICA\_USERNAME    | Yes      | Replica user name                                               |
| REPLICA\_PASSWORD    | No       | Replica user password or you'll be prompted to enter a password |

</details>

<details open>

<summary>Use Butler Python Package</summary>

Use Pylance or similar extension in your IDE to view docs

```py
from replica.butler import ReplicaButler

replicaButler = ReplicaButler()
initialized = replicaButler.initialize()

if initialized:
    response = replicaButler.ping()
    print(f'Ping response: {response}')
```

```sh
python3 my-script.py
```

</details>


---

# 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.replicacyber.com/developer-guide/butler-api-guide.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.