nqcli

nqcli is an internal CLI and lightweight web UI for running Gremlin and Cypher queries against the DTF SDR Neptune database through the AppSync GraphQL API. Requests are signed with AWS IAM (SigV4).

Quick Start

curl -fsSL https://raw.githubusercontent.com/ankit-lilly/nqcli/main/scripts/install.sh | bash
nq --help

The installer detects your OS/architecture, downloads the matching release, and installs nq to /usr/local/bin. Override the destination with INSTALL_DIR=/your/path or pin a specific release with VERSION=vX.Y.Z.

Features

• Run Gremlin (default) or Cypher queries from stdin or a file.
• Switch query language with --type gremlin|cypher.

Configuration

nqcli can read configuration from environment variables or an optional .env file. You usually do not need a .env because the AppSync URL is discovered automatically from the active AWS profile. If you do want a file, pass --env-file /path/to/file to the CLI. When omitted the tool looks for .env in the current directory and then falls back to ~/.env.

┌───────────────────────────────┬────────────────────────────────────────────────────────────┐
│ Variable                      │  Description                                               │
├───────────────────────────────┼────────────────────────────────────────────────────────────┤
│ `NEPTUNE_URL`                 │  AppSync GraphQL endpoint (overrides discovery)            │
├───────────────────────────────┼────────────────────────────────────────────────────────────┤
│ `NEPTUNE_APPSYNC_API_NAME`    │  AppSync API name to select when discovering the endpoint  │
├───────────────────────────────┼────────────────────────────────────────────────────────────┤
│ `NEPTUNE_APPSYNC_API_ID`      │  AppSync API ID to select when discovering the endpoint    │
└───────────────────────────────┴────────────────────────────────────────────────────────────┘

When NEPTUNE_URL is unset, the CLI calls appsync:ListGraphqlApis for the current --aws-profile (or AWS_PROFILE) and region to resolve the URL. The result is cached in ~/.cache/nqcli/appsync_cache.json (keyed by profile+region). Delete the cache file to force a refresh.

Example .env file (only needed if you want to override discovery):

NEPTUNE_URL=https://your-appsync-id.appsync-api.us-east-1.amazonaws.com/graphql

Note: If multiple AppSync APIs exist in the account/region, set NEPTUNE_APPSYNC_API_NAME or NEPTUNE_APPSYNC_API_ID to disambiguate.

IAM authentication

nqcli signs AppSync requests with AWS SigV4, so you must provide AWS credentials with access to the AppSync API. Use an AWS profile, environment variables, or IAM role credentials in your execution environment.

CLI Usage

Once environment variables are set, use the binary directly:

# Pipe a Gremlin query (default type)
echo 'g.V().hasLabel("Person")' | nq --aws-profile dsoadev

# Or just pass in the query as argument:

nq 'g.V().hasLabel("Person")' --aws-profile dsoadev

# Pipe a Cypher query
echo 'MATCH (n) RETURN n LIMIT 5' | nq --type cypher --aws-profile dsoadev

nq --type cypher 'MATCH (s:Study) return s.name' --aws-profile dsoadev

# Execute from a file
nq path/to/query.gql --type gremlin --aws-profile dsoadev

# Check the installed version
nq --version

If --type is omitted the command defaults to gremlin and validates that the supplied value is one of the supported options.

Use --aws-profile or --aws-region to control which AWS credentials are used when signing requests.

MCP Server (Go)

You can run an MCP server directly from the nq binary:

nq mcp

This runs over stdio and is meant to be launched by an MCP client (Claude Desktop, Cursor, etc.). See nqcli/docs/mcp.md for a short MCP primer tied to this repo.

Claude Desktop multi-environment config

Configure separate MCP servers for each AWS environment so you can switch without restarting:

{
  "mcpServers": {
    "sdr-dev": {
      "command": "nq",
      "args": ["mcp"],
      "env": {
        "AWS_PROFILE": "dsoadev"
      }
    },
    "sdr-qa": {
      "command": "nq",
      "args": ["mcp"],
      "env": {
        "AWS_PROFILE": "dsoaqa"
      }
    }
  }
}

Note that dsoadev and dsoaqa are names that I've given my aws cli sso profiles. Yours maybe be different.

Set NEPTUNE_URL (or AWS_REGION) in the env block if you need to override endpoint discovery.

Web UI

nq server --addr :8080

The server launches an interactive web UI at the provided address (default 0.0.0.0:8080).

Limitations

• Only Gremlin and Cypher queries are supported.

AWS SSO Setup

To use --aws-profile (or AWS_PROFILE) you first need to configure an AWS SSO profile locally.

Prerequisites: AWS CLI v2 — confirm with aws --version.

1. Find your SSO start URL and region

1. Go to https://lilly-aws-login.awsapps.com/start and sign in with your CA account.

2. You'll see a list of AWS accounts you have access to. Expand the account you want to use and click Access keys next to the role.

3. In the dialog that opens, note the SSO start URL and SSO region shown under "AWS IAM Identity Center credentials (Recommended)" — you'll need these in the next step.

2. Configure the profile

aws configure sso

When prompted, enter the values from the Access keys dialog:

Prompt	Value
SSO start URL	the URL from the Access keys dialog (e.g. https://identitycenter.amazonaws.com/ssoins-…)
SSO region	the region from the Access keys dialog (e.g. us-east-2)

A browser window opens to complete authentication. The CLI then asks for a few more settings:

Prompt	Example value
CLI default region	us-east-1
CLI output format	json
CLI profile name	dsoadev (pick something memorable)

3. Log in

aws sso login --profile dsoadev

This opens a browser to complete the SSO flow. You need to do this once per session (sessions last ~8 hours).

4. Run queries

nq 'g.V()' --aws-profile dsoadev

When your session expires just run aws sso login --profile <name> again.