Skip to main content

​
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

pip install graphora
PackageWhat you get
graphoraPython 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: 
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: 
import graphora

print(graphora.__version__)
# Should print: 0.4.2
If you installed the CLI, verify it works: 
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: 
export GRAPHORA_AUTH_TOKEN="your-clerk-jwt"
Or provide it directly when initializing the client: 
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: 
    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: 
export GRAPHORA_API_URL="https://api.graphora.io"
Or provide it directly when initializing the client: 
from graphora import GraphoraClient

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

​
Complete Environment Setup

Here’s a complete example of setting up your environment: 
# 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: 
from graphora import GraphoraClient

client = GraphoraClient()

​
Next steps

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