Citadel CLI

One command in the project folder: the CLI uploads the useful code, waits for the analysis and prints the grade, the flaws and their fix. No archive to prepare.

Install and log in

Create a free account at citadelscan.com, then an API key in Console › CLI & IDE. A key acts on your behalf in one workspace; it is shown once and can be revoked at any time.

Node.js 18 or later

npm install -g citadelscan
citadel login

The key is saved in ~/.citadel/config.json, readable only by you. The CITADEL_API_KEY variable, when set, takes precedence.

Analyse a project

cd my-app
citadel scan

On a project’s first analysis, the CLI asks you to confirm you own the code or may analyse it. The project is created in your workspace if it doesn’t exist.

Option	Effect
--project <name>	Citadel project (default: package.json name, else folder name)
--fail-on <severity>	Exit code 1 on any open flaw of this severity or above: critical, high, medium, low
--json	Full result as JSON (same format as the API)
--yes	Confirms you may analyse the code (required in CI)

Exit code	Meaning
0	Analysis finished
1	A flaw reached the --fail-on threshold
2	Error: invalid key, upload refused, analysis failed

What gets uploaded

In a git repository: tracked and non-ignored files, following your .gitignore. A committed .env is uploaded, since it is precisely an exposed secret to report.
Outside git: the folder, without local .env files or credential files (.ssh, .npmrc, *.pem, *.key…).
Always set aside: media, binaries, build folders, node_modules and vendor, files over 5 MB (except dependency lockfiles).
Refused: your home folder, a drive root, and a folder that doesn’t look like a code project.

Archive limited to 50 MB. Nobody at Citadel reads your code: it is analysed automatically in an isolated environment, then deleted.

Continuous integration

Add the key as a CITADEL_API_KEY secret. The build fails if a high or critical flaw is open.

GitHub Actions

- name: Citadel
  run: npx -y citadelscan scan --yes --fail-on high
  env:
    CITADEL_API_KEY: ${{ secrets.CITADEL_API_KEY }}

GitLab CI

citadel:
  image: node:22
  script:
    - npx -y citadelscan scan --yes --fail-on high
  variables:
    CITADEL_API_KEY: $CITADEL_API_KEY

Common errors

Message	What to do
Invalid or revoked API key	Create a new key in the console, then citadel login.
Archive above 50 MB	Add large data files to .gitignore, or connect the GitHub repository in the console (up to 250 MB).
Analysis quota reached	Wait for next month or upgrade your plan.
Project connected to GitHub	It is already analysed on every push: use --project with another name.

The free plan includes 10 analyses a month, CLI and MCP included, no card needed.

Nobody reads your code: it is analysed automatically in an isolated environment, then deleted. Code privacy

Create my free key