Command reference
Every global flag, environment variable, exit code and meta command in the ConnectSafely CLI, in one place.
Every command's own parameters are on the command reference page, generated from the same specification as the REST API docs. The binary carries the same information offline:
connectsafely commands # every command, one line each
connectsafely schema <command> # exact parameters, as JSON
connectsafely <command> --help # the same, formatted for a personThis page covers everything that is the same on every command.
Usage
connectsafely <command> [flags]Command names are identical to the ConnectSafely MCP tool names, and to the
operationId in the OpenAPI specification. One name always means one action,
on all three surfaces.
Meta commands
| Command | What it does |
|---|---|
commands | List every command with a one-line summary. Accepts --search <term>, --group <name>, --kind read|write — classified by what the command does, not by HTTP verb |
schema [command] | Full parameter list as JSON. With no argument, every command's schema |
batch <file|-> | Run a list of calls with pacing between writes. See Pacing |
auth login | Store an API key in ~/.connectsafely/config.json (mode 0600) |
auth status | Show the effective credentials and where each came from |
auth logout | Remove the stored key, keeping other settings |
skill | Print the router skill to stdout |
skill list | Show the eight skills in the pack and what each covers |
skill install [name...] | Write the pack into .claude/skills. Accepts --dir and --force. See Agent skills |
help | The command index |
version | The CLI version |
commands, schema, help and skill need no API key and no network — they read
the specification bundled in the binary.
Global flags
Every flag below works on every command and means the same thing everywhere.
Credentials and routing
| Flag | Description |
|---|---|
--api-key <key> | API key. Prefer CONNECTSAFELY_API_KEY in CI and agent sandboxes |
--account <id> | LinkedIn account to act as. The global spelling of each command's --account-id |
--base-url <url> | API base URL. Defaults to https://api.connectsafely.ai |
--spec <path> | Use a local OpenAPI JSON instead of the bundled specification |
Input
| Flag | Description |
|---|---|
--json <json> | The whole request payload as JSON |
--json @file.json | Read the payload from a file |
--json - | Read the payload from stdin |
Individual flags override keys of the same name inside --json. Any single string
parameter also accepts @file and -, which is how a long post body avoids shell
quoting entirely.
Output
| Flag | Description |
|---|---|
--output <mode> | json, pretty, ndjson or markdown |
--fields <mask> | Keep only these response fields, e.g. people.firstName,people.headline |
--max-items <n> | Cap every array in the response at n entries |
--quiet | Suppress progress on stderr |
--verbose | Show retry decisions and per-row batch progress on stderr |
--no-color | Disable colour (also honours NO_COLOR) |
--output defaults to pretty at an interactive terminal and json everywhere else
— a pipe, a CI job, or a recognised agent runtime. See
Cutting the cost of every answer.
Safety and reliability
| Flag | Description |
|---|---|
--dry-run | Resolve the whole request and print it. Send nothing |
--yes | Confirm a destructive command in a non-interactive shell |
--idempotency-key <k> | Make a retried write safe — a repeated key returns the first result |
--retries <n> | Attempts for retryable failures. Default 3 |
--timeout <ms> | Per-attempt timeout. Default 60000 |
Batch only
| Flag | Description |
|---|---|
--pace <min-max> | Seconds between writes. Default 30-90. A single number fixes the delay |
--no-pace | Send with no wait at all |
--stop-on-error | Halt at the first failure instead of continuing |
Skill install only
| Flag | Description |
|---|---|
--dir <path> | Where to write. Defaults to .claude/skills |
--force | Replace files you have already edited |
Environment variables
| Variable | Effect |
|---|---|
CONNECTSAFELY_API_KEY | API key. The recommended way to authenticate |
CONNECTSAFELY_ACCOUNT_ID | Default LinkedIn account for every command |
CONNECTSAFELY_API_URL | API base URL |
CONNECTSAFELY_OUTPUT | Default output mode for the session |
CONNECTSAFELY_SPEC | Path to a local OpenAPI JSON, replacing the bundled specification |
CONNECTSAFELY_CONFIG_DIR | Directory for config.json. Defaults to ~/.connectsafely |
CONNECTSAFELY_AGENT | Force agent-style output regardless of terminal detection |
NO_COLOR | Disable colour |
Precedence is flag → environment variable → config file. connectsafely auth status reports which layer supplied each value, which is usually the fastest way to
explain a surprise.
Exit codes
| Code | Name | What to do |
|---|---|---|
0 | ok | Continue |
1 | error | Read the envelope; do not retry blind |
2 | auth | Stop — the key is wrong or lacks the plan |
3 | validation | Fix the named flag and retry |
4 | confirm_required | Re-run with --yes once intent is confirmed |
5 | rate_limit | Stop this action for now; retrying will not help |
6 | network | Safe to retry a read; verify before retrying a write |
7 | unknown_command | Run connectsafely commands. Do not guess |
8 | conflict | Re-read state; the action may already have happened |
Full detail, including the error envelope and the retry policy, is in When things go wrong.
Argument syntax
--flag value # space-separated
--flag=value # equals-separated, keeps any = inside the value
--flag # a boolean flag is true
--no-flag # …and this makes it false
--flag a --flag b # repeat for an array
--flag a,b # or a comma list
--flag '["a","b"]' # or JSON
-- --literal # everything after -- is positionalUnknown flags are a hard error naming every offender at once. There is no fuzzy matching and no "did you mean" — see Not sending the wrong thing for why.
Command groups
The 87 commands are grouped for readability in --help. A command is always
addressed by its own name, so a group can never appear in an invocation.
| Group | Covers |
|---|---|
| Account & quota | Connected accounts, status, quota, invitations sent and received |
| Search & sourcing | People, companies, jobs, groups, schools, geo lookups |
| Profiles & companies | Fetching profiles, visits, endorsements, company followers |
| Relationship actions | Connect, follow, withdraw, respond to invitations |
| Inbox & messaging | Conversations, messages, attachments, reactions, sync |
| Posts & engagement | Publishing, comments, reactions, reposts, media upload |
| Analytics | SSI, network summary, creator dashboard, follower analytics |
| Groups | Group details and membership |
| Events | Event attendees |
| Sales Navigator | Threads and messaging |
connectsafely commands --group inboxThe full list, with every flag and a runnable example per command, is on the command reference page.
Related
- REST API reference — the same surface over HTTP
- CLI or MCP server? — choosing between them
- Recipes — the flags above, in real workflows
Recipes
Complete, runnable workflows — sourcing to outreach, inbox triage, content reporting and scheduled jobs — built from CLI commands you can copy today.
Integrations
Connect ConnectSafely with Zapier, Make.com, n8n, HubSpot and MCP servers for LinkedIn automation. Build powerful integrations with no code.