Getting Started

Prerequisites

Before using caido.cr, ensure your environment meets these requirements:

Installation

Add the dependency to your shard.yml:

dependencies:
  caido:
    github: hahwul/caido.cr

Then install:

shards install

Your First Program

Create a file called hello.cr:

require "caido"

# Create a client pointing to your Caido instance
client = CaidoClient.new "http://localhost:8080/graphql"

# Get current runtime info
query = CaidoQueries::Runtime.info
response = client.query(query)
puts response

Run it:

crystal run hello.cr

Authentication

caido.cr supports two authentication methods:

Environment Variable (Recommended)

Set the CAIDO_AUTH_TOKEN environment variable:

export CAIDO_AUTH_TOKEN="your-token-here"
crystal run hello.cr

The client reads this automatically when no custom headers are provided.

Custom Headers

Pass authentication headers directly:

client = CaidoClient.new(
  "http://localhost:8080/graphql",
  {"Authorization" => "Bearer your-token-here"}
)

Troubleshooting

Connection refused

Make sure Caido is running and the GraphQL endpoint is accessible:

curl http://localhost:8080/graphql

Authentication errors

Verify your token is valid. You can find it in Caido's settings or generate a new one from the Caido UI.

Missing dependencies

Run shards install to ensure crystal-gql and other dependencies are installed.