Use the Citation CLI

Install the CLI

Version 0.1.0 requires Node.js 22 or later and npm. Download the package, then run the install command from its folder. This is a local package, not an npm registry release. Installation downloads its pinned MCP client dependency.

• Download CLI

npm install --global ./citation-cli-0.1.0.tgz
citation --help
citation --version

npm pack ./packages/cli --ignore-scripts
npm install --global ./citation-cli-0.1.0.tgz
citation --help

For a project installation, run npm install ./citation-cli-0.1.0.tgz and invoke ./node_modules/.bin/citation from that project.

Connect your workspace

Create a personal token in MCP connections for the workspace and scopes you need. The production server is https://citation.co/mcp. For a local or self hosted server, use the exact configured address in settings.

• MCP setup

Provide CITATION_TOKEN through your secret manager or private standard input. Add --token-stdin for piped input. Do not include a token in a command argument, shared file or agent prompt.

# Set CITATION_TOKEN through your secret manager.
citation auth login \
  --endpoint https://citation.co/mcp

citation workspace list --json

citation auth status --json
citation documents list --limit 10 --json

Login verifies access and saves the credential in a private plaintext configuration file, not an operating system keychain. To avoid saving a credential, set CITATION_ENDPOINT and CITATION_TOKEN for the process without running login.

Each token authorizes one workspace. Use citation workspace use WORKSPACE_ID to select and verify it. A different workspace requires another token.

Work with documents and sources

Replace DOCUMENT_ID, VERSION and other placeholders with actual returned values. Add --json for structured results and --all to read every page.

citation documents list --query "research" --all --json
citation documents read DOCUMENT_ID --content --all --json
citation sources list DOCUMENT_ID --all --json

citation documents create --title "Research notes" \
  --text-file draft.txt --json

citation documents read DOCUMENT_ID --content --json
citation documents update DOCUMENT_ID --version VERSION \
  --content-file revised-content.json --request-id REQUEST_UUID --json

citation sources add DOCUMENT_ID --file source.json --json
citation references format DOCUMENT_ID --style apa --all --json
citation citations check DOCUMENT_ID --all --json

citation documents export DOCUMENT_ID \
  --format bibtex --output references.bib --json

Source files contain a title, publication type and CSL metadata. Editor files contain the document’s rich content object, not the whole read response. Preserve existing nodes, formatting and citation IDs. Plain text intentionally replaces rich content.

Citation checks inspect saved metadata and links. They do not prove originality, verify every claim or search the public web. The CLI does not expose sharing, invitations or deletion.

Save and retry changes

Read the latest document version before editing. Saves require that version, and conflicting edits are rejected. Source updates use the source’s own version hash.

Every mutation accepts --request-id UUID. The CLI generates one when omitted and includes it in the result or a connection error. It does not retry writes automatically. After an uncertain response, retry with the same ID and input. Use a new ID for a new change.

Results go to standard output. Errors go to standard error with a nonzero exit code. Exports support TXT, BibTeX and RIS, check all chunks and refuse to overwrite an existing file.

• Full command guide and file schemas

Remove access

Run citation auth logout to remove the saved token from this computer. Revoke the token in MCP connections to end server access. Clear any CITATION_TOKEN value still present in your environment separately.