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

# Query Connected Services Through Tolmo's Secure Proxy

> Proxy REST, GraphQL, and CLI requests to GitHub, AWS, Linear, Sentry, and Datadog through Tolmo. Credentials are resolved server-side and never exposed.

The `tolmo query` command proxies requests to your organization's connected services. Credentials are resolved on the backend — they never leave the server, and your local machine never sees a token or secret key. Use `tolmo query list` to discover which connected providers support proxy queries. All subcommands accept the global `--org` flag to target a specific organization.

## Discover available services

Before querying a service, use `tolmo query list` to see which providers are connected for your organization.

```bash theme={null}
# List connected services for the active org
tolmo query list

# List connected services for a specific org
tolmo query list --org superset
```

Providers are discovered dynamically from the backend. New backend adapters become available without any CLI update on your end.

## GitHub (REST)

Send REST requests directly to the GitHub API. Tolmo injects the org's GitHub App credentials on the backend.

```bash theme={null}
# List pull requests for a repository
tolmo query github '/repos/owner/repo/pulls?state=all'

# Search issues and PRs across an org
tolmo query github '/search/issues?q=type:pr+org:myorg'
```

## GitHub CLI passthrough

`tolmo query -- gh ...` runs your locally installed `gh` CLI with a short-lived token injected by the backend via a Unix socket proxy. This supports `gh` output features — including pagination, `--jq`, `--template`, and `gh api` — backed by the org's GitHub App credentials rather than your personal token.

> [!WARNING]
>
> The `--` separator between `tolmo query` and `gh` is **mandatory**. Without it, the Cobra argument parser strips unknown flags (like `--repo`, `--limit`, or `--state`) before they ever reach `gh`, causing unexpected errors or silent failures.

```bash theme={null}
# List repositories in an org
tolmo query -- gh repo list myorg --limit 50

# Search PRs with a date range using full gh api syntax
tolmo query -- gh api --method GET search/issues -f "q=type:pr org:myorg created:2026-01-01..2026-03-01" -f per_page=100

# List open issues with JSON output
tolmo query -- gh issue list --repo myorg/myrepo --state open --json number,title

# Use a different org's GitHub credentials
tolmo query --org superset -- gh api '/repos/superset-sh/superset/pulls?state=all&per_page=5'
```

## AWS CLI passthrough

`tolmo query -- aws ...` sends AWS CLI arguments to the backend, which parses and executes the supported request with your integration credentials. You do not need a local AWS CLI installation. Provider permissions and proxy restrictions still apply.

> [!WARNING]
>
> The `--` separator is **mandatory** here too. Without it, flags like `--region` and `--output` are stripped before reaching the AWS CLI.

```bash theme={null}
# Describe EC2 instances
tolmo query -- aws ec2 describe-instances

# List S3 buckets
tolmo query -- aws s3 ls

# List IAM roles in a specific region
tolmo query -- aws iam list-roles --region us-east-1

# Query a specific org's AWS environment
tolmo query --org klarify -- aws ec2 describe-security-groups --region ca-central-1
```

## Linear (GraphQL)

Send GraphQL queries to Linear. Pass the query inline as a string or load it from a file.

```bash theme={null}
# Inline GraphQL query
tolmo query linear '{ viewer { id name } }'

# Load a query from a file
tolmo query linear --file query.graphql
```

## Sentry (REST)

Send REST requests to the Sentry API. The path is appended to the Sentry base URL.

```bash theme={null}
# List issues for an organization
tolmo query sentry /api/0/organizations/acme/issues/
```

## Datadog (REST)

Send REST requests to the Datadog API. The path is appended to the Datadog base URL.

```bash theme={null}
# List all monitors
tolmo query datadog /api/v1/monitor
```

## Multiple integrations

When your organization has more than one integration for the same provider (for example, two separate GitHub App installations), pass `--integration <id>` to tell Tolmo which credentials to use. Integration IDs are shown in the output of `tolmo query list`.

```bash theme={null}
# Disambiguate when multiple GitHub integrations exist
tolmo query --integration <id> -- gh repo list

# Disambiguate a direct REST call
tolmo query --integration <id> github /repos/owner/repo/pulls
```

## Select an AWS account

When multiple AWS integrations are connected, select one by integration ID or account ID:

```bash theme={null}
tolmo query --account 123456789012 -- aws ec2 describe-instances --region us-east-1
```

## Fly.io CLI passthrough

Use `fly` or `flyctl` after the required separator. The CLI runs locally and routes supported requests through Tolmo's proxy:

```bash theme={null}
tolmo query -- fly apps list --json
```

## GraphQL variables

Pass repeatable `--var key=value` arguments with `--file`. Values are parsed as JSON when possible. Quote a JSON-looking value as a JSON string when you need to preserve it as text:

```bash theme={null}
tolmo query linear --file query.graphql --var 'limit=10' --var 'label="123"'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.