> ## Documentation Index
> Fetch the complete documentation index at: https://fentaris.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Run, validate, build, and inspect Fentaris projects from the command line.

The `fentaris` CLI creates project scaffolds, runs local development, checks project health, stores local secrets, and builds project output.

## Quick Start

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris check --help
fentaris secrets set --help
```

## Commands

### `fentaris init [project-name]`

Create a new Fentaris project in a new or empty directory.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
fentaris check
```

Options:

* `--offline` - skip network and runtime checks.
* `--strict` - fail when warnings are present.

<Tip>
  Use `fentaris check --offline` in fast local workflows or CI jobs without network access.
</Tip>

### `fentaris doctor`

Inspect local prerequisites, project files, credentials, ports, and optional runtime reachability.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

<Warning>
  Save generated API keys immediately. Fentaris stores only a hash and cannot print the raw key again.
</Warning>

### `fentaris auth api-key list`

List stored API-key counts by user without printing key values.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

<Warning>
  Do not pass `--value` in shared shell history unless the environment is trusted.
</Warning>

### `fentaris secrets list`

List credential references from the committed secrets manifest and show whether each reference is set in the local store.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "dependencies": {
    "@fentaris/core": "^2.0.0"
  },
  "fentaris": {
    "entrypoint": "src/server.ts",
    "authDir": ".fentaris"
  }
}
```

<Tip>
  Commit `.fentaris/secrets.manifest.json` and run `fentaris secrets manifest --check` in CI to catch missing or stale schema updates.
</Tip>

### `fentaris secrets doctor`

Inspect local secrets health: missing required credentials, extra stored secrets, tracked sensitive files, and manifest drift.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

## Related Documentation

* [Quickstart](/getting-started/quickstart)
* [Config file](/reference/config-file)
* [SDK-only Secrets](/guides/sdk-only-secrets)
* [Environment variables](/reference/environment-variables)
* [Troubleshooting](/troubleshooting)