CNC Execution Engine

Execute raw GraphQL queries against Constructive APIs using the cnc CLI. Manage multiple API contexts (endpoint + credentials) similar to kubectl contexts.

When to Apply

Use this skill when:

• Executing GraphQL queries against Constructive APIs
• Setting up API endpoint configurations
• Managing API tokens for authentication
• Switching between multiple API environments (dev, staging, prod)
• Testing GraphQL queries from the command line

Quick Start

# Create a context with an endpoint
cnc context create my-api --endpoint https://api.example.com/graphql

# Set your API token (input is masked)
cnc auth set-token

# Execute a query
cnc execute --query 'query { __typename }'

Context Management

Contexts store endpoint URLs and are similar to kubectl contexts. They are stored in ~/.cnc/config/contexts/.

Create a Context

# Interactive mode
cnc context create

# With flags
cnc context create my-api --endpoint https://api.example.com/graphql

List Contexts

cnc context list

Output shows all contexts with authentication status:

Contexts:

* my-api [authenticated]
    Endpoint: https://api.example.com/graphql

  staging [no token]
    Endpoint: https://staging.example.com/graphql

Switch Context

cnc context use staging

Show Current Context

cnc context current

Delete a Context

cnc context delete old-api

Authentication

Tokens are stored securely in ~/.cnc/config/credentials.json with restricted file permissions (0o600).

Set Token

# Interactive (input masked with asterisks)
cnc auth set-token

# With token as argument
cnc auth set-token eyJhbGciOiJIUzI1NiIs...

# For a specific context
cnc auth set-token --context staging

# With expiration
cnc auth set-token --expires 2024-12-31T23:59:59Z

Check Auth Status

cnc auth status

Output:

Authentication Status:

* my-api
    Status: Authenticated
    Token:  eyJhbG...s5Nw
    Expires: 2024-12-31T23:59:59Z

  staging
    Status: Not authenticated

Logout

cnc auth logout
cnc auth logout --context staging

Executing Queries

Inline Query

cnc execute --query 'query { databases { nodes { id name } } }'

From File

cnc execute --file query.graphql

With Variables

cnc execute --query 'query($id: UUID!) { database(id: $id) { name } }' \
  --variables '{"id":"550e8400-e29b-41d4-a716-446655440000"}'

Using a Specific Context

cnc execute --query 'query { __typename }' --context staging

Output Format

Successful queries return JSON:

Context: my-api
Endpoint: https://api.example.com/graphql

Success!

{
  "databases": {
    "nodes": [
      { "id": "...", "name": "my-database" }
    ]
  }
}

Failed queries show errors:

Failed!

  - Field "nonexistent" not found
    Path: query.nonexistent

Common Workflows

Setting Up a New Environment

# Create context for production
cnc context create prod --endpoint https://api.constructive.io/graphql

# Set the API token
cnc auth set-token

# Verify connection
cnc execute --query 'query { __typename }'

Working with Multiple Environments

# Create contexts for each environment
cnc context create dev --endpoint https://dev-api.example.com/graphql
cnc context create staging --endpoint https://staging-api.example.com/graphql
cnc context create prod --endpoint https://api.example.com/graphql

# Set tokens for each
cnc auth set-token --context dev
cnc auth set-token --context staging
cnc auth set-token --context prod

# Switch between environments
cnc context use dev
cnc execute --query 'query { databases { nodes { id } } }'

cnc context use prod
cnc execute --query 'query { databases { nodes { id } } }'

Scripting with CNC

#!/bin/bash
# Example: Query all databases and save to file

cnc context use prod
cnc execute --query 'query { databases { nodes { id name createdAt } } }' > databases.json

CLI Reference

cnc context

| Command | Description | |---------|-------------| | cnc context create <name> | Create a new context | | cnc context list | List all contexts | | cnc context use <name> | Switch to a context | | cnc context current | Show current context details | | cnc context delete <name> | Delete a context |

Create Options:

• --endpoint <url> - GraphQL endpoint URL

cnc auth

| Command | Description | |---------|-------------| | cnc auth set-token [token] | Set API token (masked input if no token provided) | | cnc auth status | Show authentication status for all contexts | | cnc auth logout | Remove credentials for current context |

Options:

• --context <name> - Target a specific context
• --expires <date> - Token expiration date (ISO format)

cnc execute

| Option | Description | |--------|-------------| | --query <graphql> | GraphQL query/mutation string | | --file <path> | Path to file containing GraphQL query | | --variables <json> | Variables as JSON string | | --context <name> | Context to use (defaults to current) |

File Locations

| Path | Purpose | |------|---------| | ~/.cnc/config/contexts/ | Context configuration files | | ~/.cnc/config/settings.json | Global settings (current context) | | ~/.cnc/config/credentials.json | API tokens (mode 0o600) |

Troubleshooting

| Issue | Solution | |-------|----------| | "No active context" | Run cnc context create or cnc context use | | "No valid credentials" | Run cnc auth set-token | | "Context not found" | Check cnc context list for available contexts | | Token expired | Run cnc auth set-token to set a new token | | Connection refused | Verify endpoint URL with cnc context current |

Environment Variables

The CLI respects standard environment variables but stored context/credentials take precedence:

| Variable | Description | |----------|-------------| | CNC_ENDPOINT | Override endpoint URL | | CNC_TOKEN | Override API token |

References

• CLI source: packages/cli/ in constructive-io/constructive
• Config management uses appstash for directory resolution
• Related skill: constructive-graphql-codegen for generating typed hooks/ORM