cgql

name: Cgql description: Interact with Caido HTTP proxy via its GraphQL CLI (cgql). USE WHEN caido requests OR caido findings OR caido replay OR caido automate OR cgql OR list requests OR search traffic OR create finding OR replay session OR fuzz OR automate session.

Operate the Caido HTTP proxy through the cgql CLI. Manages requests, responses, findings, replay sessions, and automate (fuzzing) sessions.

Pre-Flight (MANDATORY)

Before running ANY cgql command, always run cgql auth test first.

If auth fails:

Use the AskUserQuestion tool to ask the user for the Caido URL (default: http://localhost:8080) and access token.
Run cgql configure --url <url> --token <token> with the provided values.
Re-run cgql auth test to confirm.

Only proceed with the requested operation after auth succeeds.

Workflow Routing

Workflow	Trigger	File
Requests	"list requests", "search requests", "get request", "delete requests", "HTTPQL"	`Workflows/Requests.md`
Responses	"get response", "view response"	`Workflows/Responses.md`
Findings	"list findings", "create finding", "update finding", "delete finding"	`Workflows/Findings.md`
Replay	"replay session", "replay collection", "create replay", "list replays"	`Workflows/Replay.md`
Automate	"automate", "fuzz", "fuzzing", "start fuzzing", "automate session"	`Workflows/Automate.md`

Quick Reference

Global Flags

Flag	Description	Default
`-o, --output`	Output format (`table` or `json`)	`table`

Command Summary

Command	Description
`cgql configure`	Set Caido URL and access token
`cgql auth test`	Verify authentication
`cgql requests list`	List intercepted requests (alias: `cgql req list`)
`cgql requests get <id>`	Get request details with raw data
`cgql requests delete`	Delete requests by filter/scope
`cgql responses get <id>`	Get response details (alias: `cgql resp get`)
`cgql findings list`	List findings
`cgql findings get <id>`	Get finding details
`cgql findings create`	Create a finding
`cgql findings update <id>`	Update a finding
`cgql findings delete`	Delete findings
`cgql replay list`	List replay sessions
`cgql replay get <id>`	Get replay session details
`cgql replay create`	Create a replay session
`cgql replay delete <ids>`	Delete replay sessions
`cgql replay rename <id> <name>`	Rename a replay session
`cgql replay collections list`	List replay collections
`cgql replay collections create`	Create a collection
`cgql replay collections delete <id>`	Delete a collection
`cgql automate list`	List automate sessions
`cgql automate get <id>`	Get session details
`cgql automate create`	Create automate session
`cgql automate delete <id>`	Delete automate session
`cgql automate rename <id> <name>`	Rename session
`cgql automate start <session-id>`	Start fuzzing
`cgql automate cancel <task-id>`	Cancel running task
`cgql automate pause <task-id>`	Pause running task
`cgql automate resume <task-id>`	Resume paused task
`cgql automate tasks`	List running tasks
`cgql automate entries <session-id>`	List entries for session

HTTPQL Filtering

The --filter flag accepts HTTPQL expressions for request commands:

cgql requests list --filter "req.host = example.com"
cgql requests list --filter "req.method = POST AND resp.code >= 400"
cgql requests list --filter "req.path LIKE /api/*"

Requests List Flags

Flag	Type	Default	Description
`--filter`	string		HTTPQL filter expression
`--first`	int	`20`	Number of requests to return
`--order-by`	string	`ID`	Field to order by (ID, HOST, METHOD, PATH, QUERY, CREATED_AT, FILE_EXTENSION, SOURCE, RESP_STATUS_CODE, RESP_LENGTH, RESP_ROUNDTRIP_TIME)
`--order`	string	`DESC`	Order direction (ASC, DESC)
`--scope-id`	string		Scope ID to filter by

Findings Create Flags

Flag	Required	Description
`--request-id`	Yes	Request ID to associate
`--title`	Yes	Finding title
`--reporter`	Yes	Reporter name
`--description`	No	Detailed description
`--dedupe-key`	No	Deduplication key

Findings List Flags

Flag	Type	Default	Description
`--reporter`	string		Filter by reporter name
`--first`	int	`20`	Number of findings
`--order-by`	string	`ID`	Order by (ID, TITLE, REPORTER, HOST, PATH, CREATED_AT)
`--order`	string	`DESC`	Order direction

Replay Create Flags

Flag	Description
`--collection-id`	Place in specific collection
`--source-id`	Create from existing request ID

Automate Create Flags

Flag	Description
`--source-id`	Create from existing request ID

Output

Default output is table format for human readability.
Use -o json for scripting and piping to jq.
Always use -o json when you need to process output programmatically.

Examples

Example 1: List and filter requests

User: "Show me all POST requests to api.example.com"
→ Run auth test
→ cgql requests list --filter "req.host = api.example.com AND req.method = POST"

Example 2: Create a finding

User: "Create a finding for request 42 about an XSS vulnerability"
→ Run auth test
→ cgql findings create --request-id 42 --title "XSS Vulnerability" --reporter "manual" --description "XSS found in search parameter"

Example 3: Manage fuzzing session

User: "Start fuzzing from request 10"
→ Run auth test
→ cgql automate create --source-id 10
→ cgql automate start <session-id>
→ cgql automate tasks (to monitor)