Sortlist CLI (sl)

Command-line interface for the Sortlist platform. Talks to the GraphQL federation endpoint and dynamically discovers available operations via introspection.

Install

npm install -g @sortlist/cli
sl <command>

Local development

cd cli
npm install

npx sl <command>

Tip: add an alias to your shell profile for convenience:

alias sl='npx sl'

Authentication

Uses the Device Authorization Grant flow via Hermes. Tokens are stored at ~/.sortlist/credentials.json.

sl login          # opens browser for authentication
sl logout         # clears stored credentials
sl whoami         # shows current user
sl token          # prints access token to stdout (useful for curl/scripts)
sl switch         # switch active agency context

Service operations

Every query and mutation from the federated GraphQL schema is available as a CLI command. Operations are discovered at runtime via introspection and grouped by service based on the [service] prefix in field descriptions:

sl atlas <operation>        # company and contact enrichment
sl marketplace <operation>  # agencies, projects, opportunities, quotes
sl hermes <operation>       # OAuth/auth operations

Use --help on any service to list available operations (grouped by queries and mutations):

sl atlas --help
sl marketplace --help

Each operation supports:

| Flag | Description | | ------------------- | ---------------------------------------------- | | --depth <n> | Selection depth for nested fields (default: 0) | | --fields <a,b,c> | Comma-separated fields to include | | --exclude <a,b,c> | Comma-separated fields to exclude |

Schema management

The CLI fetches the GraphQL schema via introspection on startup and caches it locally at ~/.sortlist/schema.json (1-hour TTL). To force a refresh:

sl schema refresh

The endpoint can be configured via --endpoint, SL_ENDPOINT env var, or ~/.sortlist/config.json.

Global options

| Flag | Description | | ------------------ | ----------------------------------------------------------------------- | | --endpoint <url> | Override federation endpoint (default: http://localhost:4020/graphql) | | --json | Force JSON output (auto-enabled when non-TTY) | | --no-color | Disable colored output |

The endpoint can also be set via the SL_ENDPOINT environment variable or ~/.sortlist/config.json.

Code generation

The only build-time step is npm run codegen, which generates TypeScript types for hand-written operations (auth flow) using graphql-codegen. It reads the schema from ../backend/supergraph.graphql.

npm run generate    # alias for npm run codegen
npm run codegen     # regenerate TypeScript types for hand-written operations

This is only needed when:

• The hand-written operations in src/graphql/operations/ change
• The schema types referenced by those operations change in the supergraph

All dynamically generated commands (service operations) require no build step — they are derived entirely from runtime introspection.