### Install and Run Clairvoyance via CLI

Source: https://github.com/nikitastupin/clairvoyance/blob/main/README.md

Demonstrates how to install the Clairvoyance package using pip and execute it against a target GraphQL endpoint to generate a JSON schema file.

```bash
pip install clairvoyance
clairvoyance https://rickandmortyapi.com/graphql -o schema.json
```

--------------------------------

### Install Clairvoyance via Pip

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Installs the Clairvoyance package using the Python package manager.

```bash
pip install clairvoyance
```

--------------------------------

### Verify Clairvoyance Installation with Test Target

Source: https://github.com/nikitastupin/clairvoyance/blob/main/troubleshooting.md

This command tests if the Clairvoyance tool is functioning correctly by attempting to introspect a known working GraphQL endpoint. It saves the resulting schema to a local file, confirming basic connectivity and execution capabilities.

```bash
clairvoyance https://rickandmortyapi.com/graphql -o schema.json
```

--------------------------------

### Clairvoyance Output Format Example

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

This is an example of the JSON output generated by Clairvoyance, conforming to the standard GraphQL introspection format. This output is compatible with tools like GraphQL Voyager and InQL.

```json
{
  "data": {
    "__schema": {
      "directives": [],
      "queryType": {"name": "Query"},
      "mutationType": {"name": "Mutation"},
      "subscriptionType": null,
      "types": [
        {
          "name": "Query",
          "kind": "OBJECT",
          "fields": [
            {
              "name": "user",
              "type": {"kind": "OBJECT", "name": "User", "ofType": null},
              "args": [
                {
                  "name": "id",
                  "type": {"kind": "NON_NULL", "name": null, "ofType": {"kind": "SCALAR", "name": "ID"}}
                }
              ]
            }
          ]
        },
        {
          "name": "User",
          "kind": "OBJECT",
          "fields": [
            {"name": "id", "type": {"kind": "SCALAR", "name": "ID"}},
            {"name": "name", "type": {"kind": "SCALAR", "name": "String"}},
            {"name": "email", "type": {"kind": "SCALAR", "name": "String"}}
          ]
        }
      ]
    }
  }
}
```

--------------------------------

### Download and Use GraphQL-Specific Wordlist with Clairvoyance

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

This snippet shows how to download a pre-built GraphQL wordlist using curl and then use it with Clairvoyance to discover the schema. It also demonstrates using a general English wordlist with verbose output.

```bash
# Download GraphQL-specific wordlist from Escape Technologies
curl -o graphql-wordlist.txt https://raw.githubusercontent.com/Escape-Technologies/graphql-wordlist/main/wordlist.txt

# Use with clairvoyance
clairvoyance https://api.example.com/graphql -w graphql-wordlist.txt -o schema.json

# Use general English words
curl -o english-words.txt https://raw.githubusercontent.com/first20hours/google-10000-english/master/google-10000-english.txt
clairvoyance https://api.example.com/graphql -w english-words.txt -wv -o schema.json
```

--------------------------------

### Configure Logging Behavior (Bash)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Demonstrates how to configure logging behavior for the Clairvoyance tool using environment variables. This includes setting custom log formats, date formats, and log levels.

```bash
# Set custom log format
export LOG_FMT="%(asctime)s %(levelname)s | %(message)s"

# Set custom date format
export LOG_DATEFMT="%Y-%m-%d %H:%M:%S"

# Set log level (DEBUG, INFO, WARNING, ERROR)
export LOG_LEVEL="DEBUG"

```

--------------------------------

### Run Clairvoyance via Docker

Source: https://github.com/nikitastupin/clairvoyance/blob/main/README.md

Shows how to execute the Clairvoyance tool using a Docker container to avoid local environment dependency issues.

```bash
docker run --rm nikitastupin/clairvoyance --help
```

--------------------------------

### Perform GraphQL Schema Discovery

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Various CLI commands to discover GraphQL schemas, including basic usage, authentication, proxy configuration, and performance tuning.

```bash
# Basic usage
clairvoyance https://rickandmortyapi.com/graphql -o schema.json

# With authentication headers
clairvoyance https://api.example.com/graphql -H "Authorization: Bearer token" -o schema.json

# With proxy and SSL verification disabled
clairvoyance https://api.example.com/graphql -x http://127.0.0.1:8080 -k -o schema.json

# Custom concurrent requests and retry settings
clairvoyance https://api.example.com/graphql -c 10 -m 5 -b 2 -o schema.json
```

--------------------------------

### Probe GraphQL Endpoint with Oracle Functions (Python)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Demonstrates low-level Oracle functions for probing GraphQL endpoints. It shows how to discover valid fields, arguments, and types by analyzing error messages and responses. Requires initialization of a context with endpoint details.

```python
import asyncio
import logging
from clairvoyance import oracle
from clairvoyance.cli import setup_context

async def probe_graphql_endpoint():
    logger = logging.getLogger("clairvoyance")
    logging.basicConfig(level=logging.DEBUG)

    # Initialize context (required before using oracle functions)
    setup_context(
        url="https://api.example.com/graphql",
        logger=logger,
        headers={"Authorization": "Bearer token"},
        concurrent_requests=50
    )

    # Discover valid fields using a wordlist
    wordlist = ["user", "users", "product", "order", "admin", "login", "register"]
    valid_fields = await oracle.probe_valid_fields(
        wordlist=wordlist,
        input_document="query { FUZZ }"
    )
    print(f"Valid fields: {valid_fields}")
    # Output: {'user', 'users', 'product'}

    # Get the type of a discovered field
    typeref = await oracle.probe_field_type(
        field="users",
        input_document="query { FUZZ }"
    )
    print(f"Field type: {typeref.name} ({typeref.kind})")
    # Output: Field type: User (OBJECT)

    # Discover valid arguments for a field
    arg_wordlist = ["id", "email", "filter", "limit", "offset", "where"]
    valid_args = await oracle.probe_args(
        field="users",
        wordlist=arg_wordlist,
        input_document="query { FUZZ }"
    )
    print(f"Valid arguments: {valid_args}")
    # Output: {'filter', 'limit', 'offset'}

    # Get argument type
    arg_typeref = await oracle.probe_arg_typeref(
        field="users",
        arg="limit",
        input_document="query { FUZZ }"
    )
    print(f"Argument type: {arg_typeref.name}")
    # Output: Argument type: Int

    # Get typename for current query context
    typename = await oracle.probe_typename("query { FUZZ }")
    print(f"Root typename: {typename}")
    # Output: Root typename: Query

    # Fetch all root type names
    root_types = await oracle.fetch_root_typenames()
    print(f"Root types: {root_types}")
    # Output: {'queryType': 'Query', 'mutationType': 'Mutation', 'subscriptionType': None}

    # Explore a field completely (type + arguments)
    field, args = await oracle.explore_field(
        field_name="user",
        input_document="query { FUZZ }",
        wordlist=["id", "email", "name", "role"],
        typename="Query"
    )
    print(f"Field: {field.name} -> {field.type.name}")
    print(f"Arguments: {[a.name for a in field.args]}")
    # Output: Field: user -> User
    # Output: Arguments: ['id']

asyncio.run(probe_graphql_endpoint())

```

--------------------------------

### Run Unit Tests (Bash)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This command navigates to the clairvoyance directory and executes all unit tests found in the tests directory using Python 3's unittest module.

```bash
cd clairvoyance
python3 -m unittest tests/*_test.py
```

--------------------------------

### Run Clairvoyance with Custom Logging

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

This command demonstrates the basic usage of Clairvoyance to fetch a GraphQL schema and save it to a JSON file. It specifies the target GraphQL endpoint and an output file.

```bash
clairvoyance https://api.example.com/graphql -o schema.json
```

--------------------------------

### Tag and Push Release (Git)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This sequence of commands creates a Git tag for the new version on the main branch and then pushes this tag to the origin repository, triggering the CD process.

```git
git tag "v$V" main
git push origin "v$V"
```

--------------------------------

### GraphQL HTTP Client with Retries and Connection Pooling (Python)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Illustrates the usage of the `Client` class for making GraphQL requests. This client supports automatic retries, backoff strategies, and connection pooling, enhancing the reliability and efficiency of GraphQL interactions.

```python
import asyncio
from clairvoyance.client import Client
from clairvoyance.entities.context import client_ctx

async def make_graphql_requests():
    # Initialize client
    client = Client(
        url="https://api.example.com/graphql",
        headers={"Authorization": "Bearer token123"},
        concurrent_requests=50,
        max_retries=3,
        backoff=2,
        proxy="http://localhost:8080",
        disable_ssl_verify=False
    )

    # Make a GraphQL query
    response = await client.post("query { __typename }")
    print(f"Response: {response}")
    # Output: {'data': {'__typename': 'Query'}}

    # Test for field existence via error message
    response = await client.post("query { invalidField }")
    if "errors" in response:
        for error in response["errors"]:
            print(f"Error: {error['message']}")
            # Output: Cannot query field "invalidField" on type "Query".

    # Probe multiple fields at once
    response = await client.post("query { user product order }")
    # Each invalid field generates a separate error with suggestions

    # Close session when done
    await client.close()

asyncio.run(make_graphql_requests())
```

--------------------------------

### Create Target-Specific Wordlists for Clairvoyance

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

This section details methods for creating custom wordlists tailored to a specific target. It includes extracting names from HTTP traffic (e.g., Burp Suite exports) and from decompiled mobile application code, then combining them for use with Clairvoyance.

```bash
# Extract GraphQL names from HTTP traffic (Burp Suite export)
grep -oE '[_A-Za-z][_0-9A-Za-z]*' burp_traffic.txt | sort -u > target_wordlist.txt

# Extract from mobile app decompiled code
grep -roE '[_A-Za-z][_0-9A-Za-z]*' ./decompiled_app/ | cut -d: -f2 | sort -u > app_wordlist.txt

# Combine multiple wordlists
cat graphql-wordlist.txt target_wordlist.txt app_wordlist.txt | sort -u > combined_wordlist.txt

# Validate and use
clairvoyance https://api.example.com/graphql -w combined_wordlist.txt -wv -o schema.json
```

--------------------------------

### Commit and Push Changes (Git)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

These commands stage all changes, commit them with a message indicating a version bump, and then push the changes to the remote repository.

```git
git commit -am 'bump version'
git push
```

--------------------------------

### Perform Blind Introspection on GraphQL Endpoint (Python)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Demonstrates how to use the `blind_introspection` function to discover GraphQL schema elements by analyzing error messages. It covers basic usage, advanced configurations with authentication and proxy settings, and resuming introspection from an existing schema.

```python
import asyncio
import logging
from clairvoyance.cli import blind_introspection

async def discover_schema():
    logger = logging.getLogger("clairvoyance")
    logging.basicConfig(level=logging.INFO)

    # Basic usage
    schema_json = await blind_introspection(
        url="https://rickandmortyapi.com/graphql",
        logger=logger,
        wordlist=["id", "name", "status", "species", "type", "gender", "image", "episode", "characters", "location"],
        output_path="schema.json"
    )
    print(f"Schema discovered: {len(schema_json)} bytes")

    # Advanced usage with authentication and proxy
    schema_json = await blind_introspection(
        url="https://api.example.com/graphql",
        logger=logger,
        wordlist=["user", "email", "password", "token", "admin", "role", "permission"],
        headers={
            "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "X-Custom-Header": "value"
        },
        concurrent_requests=10,
        proxy="http://127.0.0.1:8080",
        max_retries=5,
        backoff=2,
        disable_ssl_verify=True,
        output_path="authenticated_schema.json"
    )

    # Resume from existing schema
    schema_json = await blind_introspection(
        url="https://api.example.com/graphql",
        logger=logger,
        wordlist=["field1", "field2", "field3"],
        input_schema_path="partial_schema.json",
        input_document="mutation { FUZZ }",
        output_path="complete_schema.json"
    )

asyncio.run(discover_schema())
```

--------------------------------

### Configure Logging Environment Variables

Source: https://github.com/nikitastupin/clairvoyance/blob/main/README.md

Defines environment variables for customizing the logging format, date format, and severity level within the Clairvoyance application.

```bash
LOG_FMT=`%(asctime)s \t%(levelname)s\t| %(message)s`
LOG_DATEFMT=`%Y-%m-%d %H:%M:%S`
LOG_LEVEL=`INFO`
```

--------------------------------

### Query Schema Type Keys with jq (Bash)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This command uses jq to parse the schema.json file and extract the keys from the first element of the .data.__schema.types array. This helps in understanding the structure of individual types within the schema.

```bash
cat schema.json | jq '.data.__schema.types[0] | keys'
```

--------------------------------

### Query Schema Keys with jq (Bash)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This command uses jq to parse the schema.json file and extract the top-level keys from the .data.__schema object. It demonstrates how to inspect the structure of a GraphQL schema.

```bash
cat schema.json | jq '.data.__schema | keys'
```

--------------------------------

### Set Version Environment Variable (Shell)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This command sets the V environment variable to a specific version number, which is used later in the publishing process to update the project's version.

```shell
export V=2.5.5
```

--------------------------------

### GraphQL Schema Management and Manipulation (Python)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Details the `Schema` class for managing GraphQL introspection data. This includes creating schemas, adding types and fields, defining type references and arguments, exporting to JSON, loading existing schemas, and navigating schema paths.

```python
import json
from clairvoyance.graphql import Schema, Type, Field, TypeRef, InputValue

# Create a new schema from root type names
schema = Schema(
    query_type="Query",
    mutation_type="Mutation",
    subscription_type=None
)

# Add discovered types
schema.add_type("User", "OBJECT")
schema.add_type("UserInput", "INPUT_OBJECT")

# Create fields with type references
user_typeref = TypeRef(
    name="User",
    kind="OBJECT",
    is_list=False,
    non_null=True
)

users_typeref = TypeRef(
    name="User",
    kind="OBJECT",
    is_list=True,
    non_null_item=True,
    non_null=True
)

# Create field with arguments
id_arg = InputValue(
    name="id",
    typ=TypeRef(name="ID", kind="SCALAR", non_null=True)
)

user_field = Field(
    name="user",
    typeref=user_typeref,
    args=[id_arg]
)

# Add field to Query type
schema.types["Query"].fields.append(user_field)

# Export to JSON introspection format
schema_json = repr(schema)
print(schema_json)
# Output: {"data": {"__schema": {"queryType": {"name": "Query"}, ...}}}

# Load existing schema from file
with open("existing_schema.json", "r") as f:
    existing_data = json.load(f)

loaded_schema = Schema(schema=existing_data)

# Find path from root to a nested type
path = loaded_schema.get_path_from_root("User")
print(f"Path to User: {path}")
# Output: ['Query', 'users']

# Convert path to GraphQL document
document = loaded_schema.convert_path_to_document(path)
print(f"Document: {document}")
# Output: query { users { FUZZ } }

# Find types without fields (need further exploration)
unexplored_type = loaded_schema.get_type_without_fields(
    ignored={"String", "ID", "Int", "Boolean", "Float"}
)
print(f"Unexplored type: {unexplored_type}")
```

--------------------------------

### Update pyproject.toml Version (Shell)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This command uses sed to find and replace the version string in the pyproject.toml file with the version specified in the V environment variable. This command is specifically formatted for macOS.

```shell
sed -i '' -E "s/version = \"[0-9]+\.[0-9]+\.[0-9]+\"/version = \"$V\"/" pyproject.toml
```

--------------------------------

### GraphQL Oracle Probing Functions

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Functions for programmatically probing a GraphQL endpoint to discover schema elements like fields, arguments, and types using fuzzing techniques.

```APIDOC
## POST /oracle/probe

### Description
Probes a GraphQL endpoint to discover valid fields, arguments, and types by injecting fuzzing payloads into the query document.

### Method
POST

### Parameters
#### Request Body
- **url** (string) - Required - The target GraphQL endpoint URL
- **wordlist** (list) - Required - A list of potential field or argument names to test
- **input_document** (string) - Required - The GraphQL query template containing the 'FUZZ' placeholder
- **headers** (object) - Optional - Custom HTTP headers for authentication or configuration

### Response
#### Success Response (200)
- **valid_elements** (list) - A list of discovered valid fields or arguments found via error message analysis.
```

--------------------------------

### GraphQL Query for Field Suggestions (JSON)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This JSON payload represents a GraphQL query sent to an Apollo Server. It intentionally queries for a non-existent field ('star') to trigger an error message that provides suggestions for valid fields.

```json
{
  "query": "{ star }"
}
```

--------------------------------

### Parse GraphQL Errors with Oracle Functions (Python)

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Utilizes functions to parse GraphQL error messages for extracting field and type information. This includes identifying suggested fields, argument suggestions, and determining the type references of fields and arguments.

```python
from clairvoyance.oracle import get_valid_fields, get_valid_args, get_typeref
from clairvoyance.entities.oracle import FuzzingContext

# Parse field suggestions from error messages
error1 = 'Cannot query field "usr" on type "Query". Did you mean "user"?'
fields = get_valid_fields(error1)
print(f"Suggested fields: {fields}")
# Output: Suggested fields: {'user'}

error2 = 'Cannot query field "prod" on type "Query". Did you mean "product" or "products"?'
fields = get_valid_fields(error2)
print(f"Suggested fields: {fields}")
# Output: Suggested fields: {'product', 'products'}

error3 = 'Cannot query field "x" on type "Query". Did you mean "user", "users", or "admin"?'
fields = get_valid_fields(error3)
print(f"Suggested fields: {fields}")
# Output: Suggested fields: {'user', 'users', 'admin'}

# Parse type information from error messages
error4 = 'Field "users" of type "[User!]!" must have a selection of subfields.'
typeref = get_typeref(error4, FuzzingContext.FIELD)
print(f"Type: {typeref.name}, List: {typeref.is_list}, NonNull: {typeref.non_null}")
# Output: Type: User, List: True, NonNull: True

error5 = 'Field "count" must not have a selection since type "Int" has no subfields.'
typeref = get_typeref(error5, FuzzingContext.FIELD)
print(f"Type: {typeref.name}, Kind: {typeref.kind}")
# Output: Type: Int, Kind: SCALAR

# Parse argument suggestions
error6 = 'Unknown argument "filtr" on field "users". Did you mean "filter"?'
args = get_valid_args(error6)
print(f"Suggested args: {args}")
# Output: Suggested args: {'filter'}

# Parse argument type from error
error7 = 'Field "user" argument "id" of type "ID!" is required, but it was not provided.'
typeref = get_typeref(error7, FuzzingContext.ARGUMENT)
print(f"Arg type: {typeref.name}, NonNull: {typeref.non_null}")
# Output: Arg type: ID, NonNull: True

```

--------------------------------

### GraphQL Query for Field Validation (JSON)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This JSON payload demonstrates a GraphQL query where a field ('vehicle') exists but is a complex type that requires subfields. The resulting error indicates that subfields are needed, helping to validate field existence and type.

```json
{
  "query": "{ vehicle }"
}
```

--------------------------------

### GraphQL Query with Multiple Invalid Fields (JSON)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This JSON payload sends a query with multiple intentionally incorrect fields ('star', 'spice'). The response contains separate error objects for each invalid field, including suggestions, which speeds up schema probing.

```json
{
  "query": "{ star spice }"
}
```

--------------------------------

### GraphQL Query for Argument Validation (JSON)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This JSON payload shows a GraphQL query for the 'film' field, which requires arguments like 'id'. Even without valid arguments, Apollo Server provides error messages for subfields, aiding in schema discovery.

```json
{
  "query": "{ film {id} }"
}
```

--------------------------------

### GraphQL Error Message Parsing

Source: https://context7.com/nikitastupin/clairvoyance/llms.txt

Utility functions to extract schema metadata directly from GraphQL error responses, such as field suggestions and type definitions.

```APIDOC
## POST /oracle/parse-error

### Description
Parses a raw GraphQL error string to extract suggested fields, arguments, or type information.

### Method
POST

### Parameters
#### Request Body
- **error_message** (string) - Required - The raw error string returned by the GraphQL server
- **context** (string) - Required - The context of the error (e.g., 'FIELD', 'ARGUMENT')

### Response
#### Success Response (200)
- **suggestions** (list) - Extracted field or argument names suggested by the server
- **type_info** (object) - Extracted type metadata including name, list status, and nullability
```

--------------------------------

### GraphQL Query with Typo in Field (JSON)

Source: https://github.com/nikitastupin/clairvoyance/wiki/Development

This JSON payload queries the 'film' field with a typo in a subfield ('titl' instead of 'title'). The error message from Apollo Server includes a suggestion for the correct field name, assisting in identifying field names.

```json
{
  "query": "{ film { titl } }"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.