Sortlist CLI (sl)

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

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 chat <operation>         # AI assistant (conversations, messages, configuration)
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.

Interactive chat

The chat conversation command is a hand-written interactive chat client (not auto-generated). It replaces the auto-generated basic conversation sub-command on the chat service.

Basic mode

Plain readline-based chat with streaming responses:

sl chat conversation                                     # new conversation
sl chat conversation --conversation-id <id>              # resume existing conversation
sl chat conversation --title "Debug session"             # new conversation with title

Interactive mode

Rich terminal UI with markdown rendering, thinking/tool-call visualization, and spinners:

sl chat conversation -i                                  # new conversation
sl chat conversation -i --conversation-id <id>           # resume existing conversation

Interactive mode features:

• Markdown rendering of assistant responses
• Thinking box showing tool calls with animated spinners
• Event reordering via sequence buffer (handles out-of-order WebSocket delivery)
• /quit or Ctrl+C to exit

Debug logs

The interactive chat writes debug logs to files in the cli/ directory (both gitignored):

| File | Contents | |-|-| | debug.log | Raw WebSocket events, sequence buffer warnings, finalization diagnostics | | debug-tools.log | Tool call arguments and full tool results |

Logs are cleared automatically when a new conversation starts.

tail -f debug.log              # watch WebSocket events in real time
cat debug-tools.log            # review tool calls and results

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, interactive chat) 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.