> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphora.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to install the Graphora client library and CLI

# Installation

Graphora is available as a Python package with two installation options: the client library for programmatic use, and the CLI for command-line extraction.

## Requirements

* Python 3.7 or higher
* pip (Python package installer)

## Install Options

<CodeGroup>
  ```bash Python Client Library theme={null}
  pip install graphora
  ```

  ```bash Client Library + CLI theme={null}
  pip install graphora[cli]
  ```
</CodeGroup>

| Package         | What you get                                                                 |
| --------------- | ---------------------------------------------------------------------------- |
| `graphora`      | Python client library (`GraphoraClient` class) for API integration           |
| `graphora[cli]` | Everything above plus the `graphora` CLI command for command-line extraction |

## Installing from source

If you prefer to install from source, you can clone the repository and install it using pip:

```bash theme={null}
git clone https://github.com/graphora/graphora-client.git
cd graphora-client
pip install -e ".[cli]"
```

## Dependencies

The Graphora client library has the following dependencies:

* `requests>=2.25.0` - For making HTTP requests to the Graphora API
* `pydantic>=1.8.0` - For data validation and settings management
* `pyyaml>=5.4.0` - For parsing YAML ontology files

The `cli` extra adds additional dependencies for the command-line interface.

## Verifying the installation

You can verify that the library is installed correctly by importing it in Python:

```python theme={null}
import graphora

print(graphora.__version__)
# Should print: 0.4.2
```

If you installed the CLI, verify it works:

```bash theme={null}
graphora --version
```

## Environment setup

The Graphora client library uses environment variables for configuration. You can set these variables in your environment or provide them directly when initializing the client.

### Required: Bearer token

All API calls require a Clerk-issued bearer token. Export it before making requests:

```bash theme={null}
export GRAPHORA_AUTH_TOKEN="your-clerk-jwt"
```

Or provide it directly when initializing the client:

```python theme={null}
import os
from graphora import GraphoraClient

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)
```

Passing `user_id` is optional and only used for local context; the backend derives identity from the JWT `sub` claim.

#### Pipelines / server-to-server workflows

Need to call Graphora from a CI job or data pipeline? Mint short-lived Clerk JWTs on demand—no extra Graphora code is required:

1. Create a Clerk user that represents the automation job and add a JWT template (e.g. `graphora_pipeline`) whose `aud` matches the Graphora API configuration.
2. When the job starts, request a token with your Clerk API key:
   ```bash theme={null}
   curl -X POST "https://api.clerk.com/v1/users/<USER_ID>/tokens/graphora_pipeline" \\
     -H "Authorization: Bearer $CLERK_API_KEY" \\
     -H "Content-Type: application/json" \\
     -d '{"expires_in_seconds": 3600}'
   ```
3. Export the returned `token` as `GRAPHORA_AUTH_TOKEN` (or pass it directly to `GraphoraClient`). Rotate both the JWT and the Clerk API key regularly.

### API URL

By default, the client will connect to `GRAPHORA_API_URL` (or `https://api.graphora.io` if the variable is unset). Override it when targeting staging or a local docker stack:

```bash theme={null}
export GRAPHORA_API_URL="https://api.graphora.io"
```

Or provide it directly when initializing the client:

```python theme={null}
from graphora import GraphoraClient

client = GraphoraClient(base_url="http://localhost:8000")
```

### Complete Environment Setup

Here's a complete example of setting up your environment:

```bash theme={null}
# Required
export GRAPHORA_AUTH_TOKEN="your-clerk-jwt"

# Optional overrides
export GRAPHORA_API_URL="http://localhost:8000"
```

With these environment variables set, you can initialize the client with minimal parameters:

```python theme={null}
from graphora import GraphoraClient

client = GraphoraClient()
```

## Next steps

Now that you have installed the Graphora client library, you can:

* [Read the quickstart guide](/client/quickstart) to learn how to use the library
* [Explore the core concepts](/client/concepts/ontology) to understand how Graphora works
* [Check out the examples](/client/examples/ontology) to see the library in action