Skip to main content
The Charcoal CLI lets you manage organizations, API keys, namespaces, and documents — and run searches — from your terminal. It’s distributed as an npm package and works on macOS, Linux, and Windows.

​
Install

npm install -g @charcoalhq/cli
Requires Node.js 20 or later. Verify the install with charcoal --help.

​
Log in

charcoal login
This opens your browser, walks you through authentication, and stores credentials in ~/.charcoal/credentials.json. If your account belongs to multiple organizations, the CLI prompts you to pick one. For CI or any environment without a browser, pass an existing API key: 
charcoal login --api-key $CHARCOAL_API_KEY
See Getting started for how to create an API key. Confirm who you’re logged in as with charcoal whoami.

​
Commands

Run any command with --help to see its full options.
CommandDescription
charcoal loginLog in via browser, or --api-key for headless use
charcoal logoutClear stored credentials
charcoal whoamiShow the current user and active organization
charcoal org listList organizations you belong to
charcoal org switchSwitch the active organization
charcoal org createCreate a new organization
charcoal keys listList API keys for the active organization
charcoal keys createCreate a new API key
charcoal keys deleteDelete an API key
charcoal keys setUse an existing API key as the active credential
charcoal namespacesList and manage namespaces
charcoal docs uploadUpload JSON documents from a directory
charcoal docs getFetch a document by ID
charcoal searchSearch documents in a namespace

​
Upload documents

Upload a directory of JSON files to a namespace. Each file can contain a single document or an array of documents. The namespace is created if it doesn’t exist. 
charcoal docs upload --namespace my-docs --dir ./documents
Pass a schema file to define which attributes are searchable and filterable: 
charcoal docs upload \
  --namespace my-docs \
  --dir ./documents \
  --schema-path ./schema.json
See Namespaces & Documents for the schema format. Provide an objective (one sentence describing what you’re looking for) and context (a detailed natural language query): 
charcoal search \
  --namespace my-docs \
  --objective "Fix a widget rendering error" \
  --context "A widget is failing with WIDGET_TEMPLATE_NOT_FOUND. I need to know what causes this and how to fix it."
Add --json to emit the raw response for piping into tools like jq: 
charcoal search --namespace my-docs --objective "..." --context "..." --json | jq '.results[].finding'