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

pip install graphora[cli]

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:

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:

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.

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}'

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:

Read the quickstart guide to learn how to use the library
Explore the core concepts to understand how Graphora works
Check out the examples to see the library in action

Getting Started

Core Concepts

Ontology Editor

API Reference

Examples

Installation

Installation

Requirements

Install Options

Installing from source

Dependencies

Verifying the installation

Environment setup

Required: Bearer token

Pipelines / server-to-server workflows

API URL

Complete Environment Setup

Next steps

​Installation

​Requirements

​Install Options

​Installing from source

​Dependencies

​Verifying the installation

​Environment setup

​Required: Bearer token

​Pipelines / server-to-server workflows

​API URL

​Complete Environment Setup

​Next steps

Installation

Requirements

Install Options

Installing from source

Dependencies

Verifying the installation

Environment setup

Required: Bearer token

Pipelines / server-to-server workflows

API URL

Complete Environment Setup

Next steps