CLI Usage

The fentaris CLI creates project scaffolds, runs local development, checks project health, stores local secrets, and builds project output. The fentaris edge command domain enrolls and operates governed Edge devices. The fentaris-edge binary remains available during migration.

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 edge join <control-plane-url>`

Start device authorization, create or load the protected device key, record descriptive metadata, and install the persistent per-user service when supported.

npx @fentaris/edge join https://fentaris.example --name "Mac Studio" --tag xcode --json
fentaris edge join https://fentaris.example --name "Mac Studio" --description "Local builds" --tag xcode

`fentaris edge approve <user-code>`

Approve a pending local-mode authorization through the protected operator channel. The command never edits the authority file directly.

fentaris edge approve ABCD-EFGH --subject alice
fentaris edge approve ABCD-EFGH --subject alice --tenant default --yes --json

Without --yes, the CLI asks for explicit confirmation. JSON output uses the standard { ok, data, error, warnings, pagination } envelope. Stable failures include EDGE_AUTHORIZATION_CODE_EXPIRED, EDGE_JOIN_DENIED, EDGE_DEVICE_REVOKED, EDGE_CONTROL_PLANE_INVALID_CONFIGURATION, and LOCAL_EDGE_AUTHORITY_UNAVAILABLE. Use repeatable --tag, --description, --no-service, or --service. If service installation is unavailable and --service was not required, enrollment remains valid and the result gives the exact foreground command.

`fentaris edge run`

Run the enrolled agent in the foreground with singleton protection, automatic reconnect, local status, and graceful workload cleanup.

fentaris edge run

`fentaris edge service <operation>`

Manage the local per-user service with install, start, stop, restart, or uninstall.

fentaris edge service restart --json

Service uninstall removes background operation but retains enrollment identity.

`fentaris edge list|get|status|update`

Discover and manage only devices visible to the selected Fentaris identity.

fentaris edge list --as user:alice --compact --limit 20 --json
fentaris edge get "Mac Studio" --include readiness,observed --json
fentaris edge status
fentaris edge update "Mac Studio" --expected-version 4 --description "Build machine" --tag xcode --json

Discovery commands support --json, --compact, --limit, --cursor, --include, --exclude, and --as user:<name>|group:<name>. JSON uses { ok, data|error, pagination, warnings, nextActions }.

`fentaris edge disconnect|revoke <device>`

Both mutations require an explicit public device name and confirmation. Automation must pass --yes.

fentaris edge disconnect "Mac Studio" --yes --json
fentaris edge revoke "Mac Studio" --yes --json

disconnect closes the active channel without deleting enrollment identity. revoke invalidates the device authorization.

`fentaris edge installation <operation> [deployment-id]`

Inspect and operate managed MCP installations through the protected local control channel.

fentaris edge installation status --json
fentaris edge installation review filesystem --json
fentaris edge installation approve filesystem --yes --json
fentaris edge installation deny filesystem --yes --json
fentaris edge installation retry filesystem --yes --json
fentaris edge installation revoke filesystem --yes --json
fentaris edge installation cleanup filesystem --yes --json

Mutations require interactive confirmation or --yes. review, approve, and deny accept --cleanup to address the independent approval identity for custom cleanup with external side effects. JSON retains the canonical { ok, data|error, pagination, warnings, nextActions } envelope and separates device, service, installation, setup, workload, and readiness state.

cleanup blocks the dependent workload first. Shared managed artifacts remain present until their final deployment reference is removed. Manual prerequisites are never removed automatically.

Legacy `fentaris-edge` commands

fentaris-edge login|status|disconnect|revoke map to the new services and add migration warnings without removing existing JSON fields. New automation should use fentaris edge. The executable and package allowlists are deny-by-default. See Environment Variables for configuration.

Neither CLI surface has an add command. MCP definitions, setup schemas, targets, and assignments are managed by the Fentaris application.

`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
fentaris check --offline --json

Options:

--offline - skip network and runtime checks.
--strict - fail when warnings are present.
--json - print machine-readable project check results.
--verbose - list passed checks in human-readable output. This flag has no effect with --json.

--json writes one JSON document with a results array. Each result includes its group, label, status, and detail, plus a hint or metadata when available. Exit codes remain unchanged: failures return 1, and warnings return 1 when combined with --strict.

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 tools list`

List effective MCP tools for a configured account context.

fentaris tools list --mcp github --as user:alice --compact --json

Options:

--json - print the agent-facing JSON envelope.
--compact - return compact metadata instead of detailed schema-oriented records.
--limit <n> - maximum tools returned. Default: 20.
--cursor <cursor> - continue from a previous page.
--max-tokens <n> - apply a best-effort response budget and return narrowing guidance when truncated.
--mcp <name> - restrict discovery to one upstream MCP server.
--as <selector> - use a configured selector such as user:alice or group:support.
--include <text> - include only matching tools. Comma-separated values are accepted.
--exclude <text> - exclude matching tools. Comma-separated values are accepted.
--refresh - request fresh discovery metadata where supported.
--no-start - do not start stdio MCP servers during discovery.

JSON responses include ok, data, warnings, and nextActions. Collection responses also include pagination.

`fentaris tools search <query>`

Search effective tools without loading every schema.

fentaris tools search issue --mcp github --as user:alice --limit 10 --json

The command supports the same discovery flags as tools list and returns follow-up commands for exact inspection.

`fentaris tools get <tool>`

Inspect one tool’s availability and metadata.

fentaris tools get github__create_issue --json

The tool name is the proxied Fentaris name, for example github__create_issue.

`fentaris tools schema <tool>`

Inspect one tool schema without returning unrelated schemas.

fentaris tools schema github__create_issue --input --output --json

Options:

--input - include the input schema.
--output - include the output schema when the upstream MCP server declares one.

If an output schema is unavailable, the JSON response reports explicit availability metadata instead of inventing a schema.

`fentaris tools auth`

Inspect configured MCP account selectors and login state without printing secrets.

fentaris tools auth list --json
fentaris tools auth status --mcp github --as user:alice --json
fentaris tools auth login --mcp github --as user:alice --json

auth list returns each configured MCP key, its default selector, allowed selectors, and non-sensitive status. auth login starts a supported login flow when available or returns machine-readable delegated login instructions.

`fentaris auth`

Open the guided local API-key menu:

fentaris auth

Choose whether to add, list, or remove an API key. Add and remove flows select known users from the entrypoint, secrets manifest, and encrypted credential store. They show a redacted review and require confirmation before changing the store. Generated projects are discovered from fentaris.json. SDK-only projects are discovered from the nearest package.json that depends on @fentaris/core. Use the explicit fentaris auth api-key commands with --non-interactive in automation.

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

fentaris auth api-key add
printf '%s' "$ADMIN_API_KEY" | fentaris auth api-key add alice --value-stdin
fentaris auth api-key add alice --generate

When the user id is omitted, the command offers known users and allows manual entry. When no key value option is present, choose whether to generate a new key or enter an existing key, then review and confirm the change. 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. Auth and secrets commands read FENTARIS_AUTH_KEY from the exported environment or the discovered project .env before prompting. An exported value takes precedence over .env. 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 setup`

Discover every credential and Fentaris user API-key requirement in the project entrypoint, then configure everything that the local backend supports.

fentaris secrets setup
fentaris secrets setup --dry-run
fentaris secrets setup --yes --json
fentaris secrets setup --non-interactive --yes --json

Interactive setup shows a redacted plan, prompts invisibly for missing third-party tokens, creates FENTARIS_AUTH_KEY in the ignored project .env when an encrypted local store is needed, and generates missing Fentaris API keys. Generated client API keys are printed only after a successful write; save them immediately because the store retains only their hashes. Rerunning setup does not replace configured credentials or regenerate existing keys. Options:

--entrypoint <path> - scan a specific TypeScript entrypoint.
--dry-run - show planned prompts, generation, and manual actions without changing files.
--yes - apply a complete plan without confirmation.
--non-interactive - disable prompts. This is a global option and can appear anywhere in the command.
--json - emit the canonical machine-readable envelope.
--key <key> - use an explicit local-store encryption key.

JSON and non-interactive setup validates all non-generatable values before writing. If an external value is unavailable, it exits with SECRETS_SETUP_INCOMPLETE, leaves .env, the encrypted store, and the manifest unchanged, and returns commands in nextActions. Fentaris never invents third-party tokens. Custom JSON files or non-standard paths are reported as manual actions.

`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(...), credentialJson(...), and credentialEnv(...) declarations in the project entrypoint. The manifest contains source metadata and Fentaris user API-key counts, but never credential values.

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.

Home

Documentation

Quick Start

Global Flags

Commands

`fentaris edge join <control-plane-url>`

`fentaris edge approve <user-code>`

`fentaris edge run`

`fentaris edge service <operation>`

`fentaris edge list|get|status|update`

`fentaris edge disconnect|revoke <device>`

`fentaris edge installation <operation> [deployment-id]`

Legacy `fentaris-edge` commands

`fentaris init [project-name]`

`fentaris dev`

`fentaris check`

`fentaris doctor`

`fentaris build`

`fentaris tools list`

`fentaris tools search <query>`

`fentaris tools get <tool>`

`fentaris tools schema <tool>`

`fentaris tools auth`

`fentaris auth`

`fentaris auth api-key add [user-id]`

`fentaris auth api-key list`

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

`fentaris secrets set [reference]`

`fentaris secrets setup`

`fentaris secrets list`

`fentaris secrets unset <reference>`

`fentaris secrets manifest`

`fentaris secrets doctor`

Exit Codes

Project Discovery

​Quick Start

​Global Flags

​Commands

​fentaris edge join <control-plane-url>

​fentaris edge approve <user-code>

​fentaris edge run

​fentaris edge service <operation>

​fentaris edge list|get|status|update

​fentaris edge disconnect|revoke <device>

​fentaris edge installation <operation> [deployment-id]

​Legacy fentaris-edge commands

​fentaris init [project-name]

​fentaris dev

​fentaris check

​fentaris doctor

​fentaris build

​fentaris tools list

​fentaris tools search <query>

​fentaris tools get <tool>

​fentaris tools schema <tool>

​fentaris tools auth

​fentaris auth

​fentaris auth api-key add [user-id]

​fentaris auth api-key list

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

​fentaris secrets set [reference]

​fentaris secrets setup

​fentaris secrets list

​fentaris secrets unset <reference>

​fentaris secrets manifest

​fentaris secrets doctor

​Exit Codes

​Project Discovery

​Related Documentation

Quick Start

Global Flags

Commands

`fentaris edge join <control-plane-url>`

`fentaris edge approve <user-code>`

`fentaris edge run`

`fentaris edge service <operation>`

`fentaris edge list|get|status|update`

`fentaris edge disconnect|revoke <device>`

`fentaris edge installation <operation> [deployment-id]`

Legacy `fentaris-edge` commands

`fentaris init [project-name]`

`fentaris dev`

`fentaris check`

`fentaris doctor`

`fentaris build`

`fentaris tools list`

`fentaris tools search <query>`

`fentaris tools get <tool>`

`fentaris tools schema <tool>`

`fentaris tools auth`

`fentaris auth`

`fentaris auth api-key add [user-id]`

`fentaris auth api-key list`

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

`fentaris secrets set [reference]`

`fentaris secrets setup`

`fentaris secrets list`

`fentaris secrets unset <reference>`

`fentaris secrets manifest`

`fentaris secrets doctor`

Exit Codes

Project Discovery

Related Documentation