# Use the Citation CLI

Work with saved documents, sources and references from your terminal or scripts.

## 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](/downloads/ai/citation-cli-0.1.0.tgz)

Install the downloaded package
```sh
npm install --global ./citation-cli-0.1.0.tgz
citation --help
citation --version
```

### Install from the repository

Run these commands from the Citation repository root.

From the Citation repository root
```sh
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](/docs/mcp)

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.

Connect using a secret environment
```sh
# Set CITATION_TOKEN through your secret manager.
citation auth login \
  --endpoint https://citation.co/mcp

citation workspace list --json
```

A first command
```sh
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.

### Read

Read saved work
```sh
citation documents list --query "research" --all --json
citation documents read DOCUMENT_ID --content --all --json
citation sources list DOCUMENT_ID --all --json
```

### Write

Save a requested change
```sh
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
```

### Cite

Use saved source metadata
```sh
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
```

### Export

Export a bibliography
```sh
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](/downloads/ai/cli-guide.md)

## 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.