Skip to main content
The fentaris CLI creates project scaffolds, runs local development, checks project health, stores local secrets, and builds project output.

​
Quick Start

fentaris init my-proxy
cd my-proxy
fentaris dev

​
Global Flags

  • --help, -h - print CLI usage.
  • --version, -v - print the CLI version.
  • --non-interactive - fail instead of prompting for input. Use this in automation and agent-driven runs.
Help is contextual. Use fentaris <command> --help, fentaris auth <command> --help, or fentaris secrets <command> --help to print usage, arguments, and options for one command. --non-interactive is accepted on every command. Commands that already have all required values continue normally; commands that would need a prompt return a runtime error instead of waiting for input. 
fentaris check --help
fentaris secrets set --help

​
Commands

​
fentaris init [project-name]

Create a new Fentaris project in a new or empty directory. 
fentaris init my-proxy
Options:
  • --package-manager <pm> - set the generated project’s package manager. Supported values: pnpm, npm, and bun. When install runs, this binary must be available on PATH.
  • --port <port> - set the generated proxy port. Default: 4000.
  • --path <path> - set the generated MCP endpoint path. Default: /mcp.
  • --core-version <range> - set the version range for @fentaris/core written to the generated package.json. Default: ^2.0.0. Accepts semver ranges (^2.0.0, ~2.0.0, 2.0.0, >=2.0.0), dist tags (latest, next), and workspace/file references (workspace:*, file:../packages/core). Use workspace:* or a file: reference to link a generated project against the local Fentaris monorepo.
  • --skip-install - create files without running package installation.
  • --skip-git - create files without initializing a git repository.
init writes fentaris.json, src/index.ts, package scripts, TypeScript config, .gitignore, and a README. It initializes a git repository when git is available unless --skip-git is passed. The generated package.json pins @fentaris/core to the version range this CLI was released against, so the proxy always starts against a known-good core. Use --non-interactive with an explicit project name. Pass --package-manager when the environment has more than one supported package manager or when automation must be reproducible. 
fentaris init my-proxy --non-interactive --package-manager pnpm --port 4000 --path /mcp --skip-install --skip-git
When developing against the local Fentaris monorepo, pass --core-version workspace:* from a workspace package or --core-version file:../packages/core from an adjacent generated project. The generated app then imports the local @fentaris/core instead of the released range.

​
fentaris dev

Run the generated project’s dev script. 
fentaris dev
The CLI discovers the nearest fentaris.json from the current directory upward and prints the configured local endpoint before starting the script.

​
fentaris check

Validate the project configuration and local files. 
fentaris check
Options:
  • --offline - skip network and runtime checks.
  • --strict - fail when warnings are present.
Use fentaris check --offline in fast local workflows or CI jobs without network access.

​
fentaris doctor

Inspect local prerequisites, project files, credentials, ports, and optional runtime reachability. 
fentaris doctor
Options:
  • --fix - apply supported automatic fixes.
  • --strict - fail when warnings are present.
  • --json - print machine-readable results.
  • --runtime - check the running MCP endpoint.
  • --timeout <ms> - set runtime check timeout. Default: 10000.
When project dependencies have not been installed, doctor reports node_modules/@fentaris/core as a warning and prints the package manager install command to run.

​
fentaris build

Validate the project offline, run the generated project’s build script, write compiled TypeScript output to dist/index.js, and write Fentaris metadata to .fentaris/build/manifest.json. 
fentaris build
The built proxy runs with node dist/index.js or the generated project’s npm start script.

​
fentaris auth api-key add <user-id>

Store a local API key for a user identity. Clients send this value in the x-fentaris-api-key header when connecting to Fentaris. 
printf '%s' "$ADMIN_API_KEY" | fentaris auth api-key add alice --value-stdin
fentaris auth api-key add alice --generate
The raw API key is never stored. Fentaris writes a sha256: hash into .fentaris/credentials.enc.json and compares incoming client keys against that hash. Options:
  • --value <key> - pass the API key non-interactively.
  • --value-stdin - read the API key from standard input.
  • --generate - generate a new API key, print it once, and store only its hash.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.
Save generated API keys immediately. Fentaris stores only a hash and cannot print the raw key again.

​
fentaris auth api-key list

List stored API-key counts by user without printing key values. 
fentaris auth api-key list
fentaris auth api-key list --user alice --json
Options:
  • --user <id> - only list API-key counts for one user.
  • --json - print machine-readable output.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.

​
fentaris auth api-key remove <user-id>

Remove a local API key from a user by providing the raw value to match. 
printf '%s' "$OLD_ADMIN_API_KEY" | fentaris auth api-key remove alice --value-stdin
Options:
  • --value <key> - pass the API key to remove non-interactively.
  • --value-stdin - read the API key to remove from standard input.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.

​
fentaris secrets set [reference]

Store a secret in the local encrypted credential store. 
fentaris secrets set
fentaris secrets set github.token --user admin
fentaris secrets set github.token --value-stdin --non-interactive
Generated projects are discovered from fentaris.json. SDK-only projects are discovered from the nearest package.json that depends on @fentaris/core; in that mode the CLI uses .fentaris/ unless package.json contains a fentaris.authDir override. When reference or --value is omitted, the command walks through an interactive setup: pick a manifest reference, choose default, user, or group scope, enter the hidden value, review the redacted summary, and confirm before anything is written. Options:
  • --user <id> - store a user-scoped credential.
  • --group <id> - store a group-scoped credential.
  • --value <secret> - pass the value non-interactively.
  • --value-stdin - read the value from standard input.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.
Use --value=<secret> when a scripted secret value starts with -, for example --value=-token.
Do not pass --value in shared shell history unless the environment is trusted.

​
fentaris secrets list

List credential references from the committed secrets manifest and show whether each reference is set in the local store. 
fentaris secrets list
Options:
  • --json - print machine-readable output with reference, scope, and status fields.
  • --user <id> - list secrets for a user scope when opening the local store.
  • --group <id> - list secrets for a group scope when opening the local store.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.
Secret values are never printed.

​
fentaris secrets unset <reference>

Remove a secret from the local encrypted credential store. 
fentaris secrets unset github.token --group support
Options:
  • --user <id> - remove a user-scoped credential.
  • --group <id> - remove a group-scoped credential.
  • --key <key> - use an explicit encryption key instead of prompting or reading FENTARIS_AUTH_KEY.

​
fentaris secrets manifest

Generate or validate .fentaris/secrets.manifest.json from credential(...) references in the project entrypoint. 
fentaris secrets manifest
fentaris secrets manifest --entrypoint src/server.ts
fentaris secrets manifest --check
Options:
  • --entrypoint <path> - scan this entrypoint. Use it for SDK-only projects without fentaris.json or to override the configured entrypoint.
  • --check - fail when the committed manifest does not match the entrypoint scan.
SDK-only projects can also declare the entrypoint in package.json: 
{
  "dependencies": {
    "@fentaris/core": "^2.0.0"
  },
  "fentaris": {
    "entrypoint": "src/server.ts",
    "authDir": ".fentaris"
  }
}
Commit .fentaris/secrets.manifest.json and run fentaris secrets manifest --check in CI to catch missing or stale schema updates.

​
fentaris secrets doctor

Inspect local secrets health: missing required credentials, extra stored secrets, tracked sensitive files, and manifest drift. 
fentaris secrets doctor
fentaris secrets doctor --strict
Options:
  • --strict - treat warnings as failures.
  • --json - print machine-readable issue output.
fentaris doctor also includes secrets checks in its Auth group when a secrets manifest or entrypoint credential references are present.

​
Exit Codes

  • 0 - command completed successfully, or help/version output was printed.
  • 1 - runtime error, such as running a project command outside a Fentaris project.
  • 2 - command syntax error, such as an unknown command, unknown option, or missing required argument.
Syntax errors print error: ..., the relevant Usage: ..., and a --help hint before exiting.

​
Project Discovery

Project commands search upward from the current directory for fentaris.json. Legacy fentaris.config.json is still detected, but generated projects use fentaris.json.