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.

Cgql

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:

1. Use the AskUserQuestion tool to ask the user for the Caido URL (default: http://localhost:8080) and access token.
2. Run cgql configure --url <url> --token <token> with the provided values.
3. 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

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)