socket.help

socket-help command line interface

Use the socket-help CLI to run utilities from a pipe, create webhook inboxes, upload and download files, and call any /api/ endpoint with JSON output.

Updated 27 October 2026

What the CLI is for

socket-help is a small command line client for shell scripts and CI. It reads input from standard input, prints JSON to standard output, writes errors as JSON to standard error and exits with a nonzero code on failure. It is built on the TypeScript SDK.

The CLI ships in the repository as a workspace package, not as a published npm package. Build it with pnpm build:packages and run pnpm cli --help, or create an installable tarball with pnpm --filter @socket-help/cli pack.

Configure

The CLI reads three environment variables. Without an API key it works anonymously.

Environment variables
VariablePurpose
SOCKET_HELP_URLAPI origin; defaults to https://socket.help
SOCKET_HELP_API_KEYWorkspace API key sent as a Bearer token
SOCKET_HELP_ACCESS_TOKENAccess token used by download when --access-token is not given

Commands

Creation commands default to private visibility and also accept --ttl-seconds <n> and --persistent.

socket-help commands
CommandWhat it does
socket-help toolsList tools (GET /api/tools)
socket-help describe <tool-id>Show one tool and its options
socket-help usageShow your plan, limits and runs today
socket-help resourcesList workspace resources (needs an API key)
socket-help run <tool-id> [--options JSON] [--file <name>]Run a utility with standard input as text, or as file bytes with --file
socket-help inbox create [--visibility private|public]Create a webhook inbox
socket-help upload <filename> [--visibility ...] [--max-downloads n]Upload standard input as a file
socket-help download <file-id> [--access-token token]Write file bytes to standard output
socket-help api <METHOD> /api/path [--token <resource-token>]Call any /api/ endpoint with standard input as the JSON body
Examples
export SOCKET_HELP_API_KEY='sh_...'

printf '{"hello":true}' | socket-help run json --options '{"action":"minify"}'
socket-help run everyday-file-checksums --file report.pdf < report.pdf

socket-help inbox create
socket-help upload report.txt --max-downloads 1 < report.txt
socket-help download FILE_ID --access-token "$ACCESS_TOKEN" > report.txt

socket-help api GET /api/inboxes/INBOX_ID/requests --token "$INSPECTION_TOKEN"
socket-help api DELETE /api/mocks/MOCK_ID --token "$MANAGEMENT_TOKEN"

Output and errors

  • Results print as indented JSON; download prints raw bytes; help prints plain text.
  • Errors print {"error", "status", "requestId", "retryAfter"} to standard error and exit with code 1.
  • Standard input is limited to 10 MiB. Requests time out after 90 seconds.
  • Mutations are never retried automatically.
  • The api command sends the --token value in X-Resource-Token, so it works alongside an API key.

Frequently asked questions

How do I install the socket-help CLI?

It is a repository package. Run pnpm build:packages, then pnpm cli --help, or pnpm --filter @socket-help/cli pack to build a tarball you can install with npm.

How do I run a multi-file tool such as PDF merging from the CLI?

Use the api command: pipe a JSON body with a file array to socket-help api POST /api/tools/everyday-merge-pdfs/run.

How do I point the CLI at a self-hosted installation?

Set SOCKET_HELP_URL to its origin. Remote origins must use HTTPS; plain HTTP is allowed only for localhost.