query

You are helping the user query cloud infrastructure and SaaS resources using StackQL.

Input: $@

Follow these steps in order.

Step 1 - Check StackQL is installed

command -v stackql

If not found, delegate to /stackql-skills:install-stackql and then continue.

Step 2 - Resolve auth

Check if there is an auth configuration available. Look for:

1. A .stackqlrc file in the current directory or home directory
2. Environment variables for common providers (e.g., GOOGLE_CREDENTIALS, AWS_ACCESS_KEY_ID, AZURE_CLIENT_ID, GITHUB_TOKEN)

Build the --auth JSON string from what's available. If no credentials are found for the provider referenced in the query, suggest using /stackql-skills:auth-setup <provider>.

Step 3 - Identify the provider and check it's pulled

Extract the provider name from the query (e.g., google from google.compute.instances).

stackql exec "SHOW PROVIDERS;" --output json

If the provider is not installed, delegate to /stackql-skills:pull-provider <provider> and then continue.

Step 4 - Generate SQL if needed

If the input is natural language (not valid StackQL SQL), generate the appropriate query:

1. First, explore the relevant resources to understand the schema:

stackql exec "SHOW SERVICES IN <provider>;" --output json

Then narrow down to the relevant service and resource:

stackql exec "SHOW RESOURCES IN <provider>.<service>;" --output json
stackql exec "DESCRIBE <provider>.<service>.<resource>;" --output json

2. Use the schema to generate the correct StackQL SQL. Key patterns:

Read (SELECT):

SELECT id, name, status
FROM <provider>.<service>.<resource>
WHERE region = 'us-east-1';

Create (INSERT):

INSERT INTO <provider>.<service>.<resource> (project, zone, name, ...)
SELECT 'my-project', 'us-central1-a', 'my-resource', ...;

Modify (UPDATE):

UPDATE <provider>.<service>.<resource>
SET <field> = <value>
WHERE <identifiers>;

Remove (DELETE):

DELETE FROM <provider>.<service>.<resource>
WHERE <identifiers>;

Lifecycle (EXEC):

EXEC <provider>.<service>.<resource>.<method>
@param1 = 'value1', @param2 = 'value2';

Important: StackQL requires WHERE clauses for provider-specific parameters like project, region, zone, subscriptionId, etc. Check the DESCRIBE output for required parameters.

Step 5 - Confirm destructive operations

If the generated query is an INSERT, UPDATE, DELETE, or EXEC operation, show the query to the user and ask for confirmation before executing.

This will execute the following against your cloud environment:

<QUERY>

Proceed?

Do NOT execute destructive operations without explicit user confirmation.

Step 6 - Execute the query

stackql exec "<QUERY>" --auth="${AUTH}" --output json

For queries that may return large result sets, add a practical limit or use --output csv for more compact output.

For multi-line queries, use a heredoc:

stackql exec --auth="${AUTH}" --output json <<'SQL'
<QUERY>
SQL

Step 7 - Handle errors

• Provider not found: delegate to /stackql-skills:pull-provider <provider>
• Authentication error: suggest /stackql-skills:auth-setup <provider>
• Resource not found: use /stackql-skills:explore <provider> to help find the correct resource path
• Required parameter missing: check DESCRIBE output and add missing WHERE clause parameters
• Syntax or API error: use /stackql-skills:stackql-docs <error keywords> to search for guidance
• Timeout: suggest increasing --apirequesttimeout or narrowing the query scope

Step 8 - Present results

Show the query output to the user. For JSON output, format it clearly.

For natural language questions, provide a brief interpretation of the results.

If the result set is large, summarize key findings and offer to drill down further.

Suggest related queries the user might find useful based on the results.