Skip to main content
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

​
Global Flags

  • --help, -h - print CLI usage.
  • --version, -v - print the CLI version.
  • --json - auth/secrets emit a machine-readable result without terminal prompts.
  • --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.

​
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.
The command prints the verification URL, user code, and exact approval command as soon as authorization begins. Keep edge join running and approve the displayed code from a second terminal. With --json, the final canonical envelope remains on standard output. The pending verification event is emitted immediately as compact JSON on standard error with type edge.verification_required, so scripts can surface the approval step without corrupting the final JSON result.

​
fentaris edge approve <user-code>

Approve a pending local-mode authorization through the protected operator channel. The command never edits the authority file directly.
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 service <operation>

Manage the local per-user service with install, start, stop, restart, or uninstall.
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.
Discovery commands support --json, --compact, --limit, --cursor, --include, --exclude, and --as user:<name>|group:<name>. JSON uses { ok, data|error, pagination, warnings, nextActions }. Inside a project using the integrated local control plane, these commands use the owner-protected local operator channel automatically. Local discovery supports --as user:<name>, --compact, --include, and --exclude; --as group:<name> requires a remote control plane. Outside that project, set FENTARIS_EDGE_CONTROL_PLANE_URL to use a remote management API.

​
fentaris edge disconnect|revoke <device>

Both mutations require an explicit public device name and confirmation. Automation must pass --yes.
disconnect closes the active channel without deleting enrollment identity. revoke invalidates the device authorization. For the integrated local control plane, both operations use the protected operator channel and revoke also updates the durable authority store. The revoked agent stops reconnecting with EDGE_UNAUTHORIZED_TARGET; fentaris edge status --json then directs the operator to join it again with a new authorization.

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

Inspect and operate managed MCP installations through the protected local control channel.
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.
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: ^3.0.0. Accepts semver ranges (^3.0.0, ~3.0.0, 3.0.0, >=3.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.
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.
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.
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.
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.
The built proxy runs with node dist/index.js or the generated project’s npm start script.

​
fentaris mcp

Inspect every configured upstream connection without a downstream client identity. Multiple named accounts appear as separate rows, including connections that need login or cannot be reached. Configuration validity, local authorization state, and connectivity are separate facts.
Live checks have a 5000 ms deadline per connection and at most four connections run concurrently. Override the deadline with --timeout <milliseconds> (1–60000). Verified tool counts include zero only when the server actually exposes no tools. Offline metadata is marked cached with its age; absent counts are — in text and null in JSON. Endpoints omit credentials, query strings, and fragments. Provider identity and permissions appear only when the provider supplies them; account aliases never imply provider identity.

​
fentaris mcp tools

Discover tools grouped by MCP and account. Optional filters remain optional. Healthy results survive failures on other connections. Terminal progress is cleared on completion, and temporary clients, sessions, and subprocesses are closed.
Tool get/schema requires an explicit account when the MCP has several accounts; a single account is inferred. MCP details without an account show every account. Schema output contains inputSchema and/or outputSchema; an unavailable output schema is null. Without either schema flag both schemas are included.

​
fentaris mcp auth

Bare auth shows an inventory. In a terminal, choose an action, server, and account; mutations selected from this menu require explicit confirmation. Explicit action commands progressively ask only for missing required fields and preserve supplied flags, including a recognized value-taking flag supplied without its value.
Connect chooses browser OAuth, hidden credential input, reuse of a named secret, or an explanation that authentication is unnecessary or managed by the upstream. Existing credentials are preserved unless --reauth explicitly requests replacement. --secret reuses one existing reference; a credential bundle completes each configured reference individually. Repeat --credential SLOT=REFERENCE to reuse several existing named secrets (slots are bearer, an HTTP header name, or an environment name). Disconnect disables only the selected connection, preserves shared secrets, and reports remote OAuth revocation as revoked, unsupported, failed, or unnecessary. For headless OAuth, supply --print-url --non-interactive; the authorization URL goes to stderr and the command waits for a browser callback. OAuth --timeout is in milliseconds, defaults to 300000, and accepts 1–300000. --port chooses a fixed loopback port for pre-registered clients. JSON authorization-code flows also require explicit --print-url; client-credentials flows need no browser. Store credentials through the project vault; supply its unlock key through the environment, or --key for explicit auth actions. Read commands do not create a vault key.

​
Read flags and exit codes

All MCP commands accept --json and global --non-interactive. JSON emits one versioned result on stdout without prompts, banners, or progress. Non-TTY execution never waits for terminal input. Missing fields produce a nonzero result with error.code = "MISSING_INPUT", missingFields, and a complete nextCommand. Unknown flags and invalid supplied values remain errors. --offline is available on inventory, get, tools, and auth get. It reads configuration, credential metadata, and cached schemas without contacting upstreams, spawning processes, or starting OAuth. Configuration modules must be safe to import: export fentarisConfig, config, or a default config and start the proxy only on direct execution. The project .env is loaded before importing that configuration; defined process environment values win. Disconnect also returns 3 when local disconnect succeeded but remote revocation failed. Authentication mutations otherwise return 0 on success or 1 on failure. Discovery JSON uses { version: 1, outcome, offline, connections, summary, exitCode }. Each connection has server, account, configuration, authentication, connectivity, status, toolCount, tools, toolMetadata, recovery, and optional error. Tool get/schema adds data. Authentication mutations use { version: 1, ok: true, data }; command errors use { version: 1, ok: false, error }. Secret values are never part of these results.

​
Migration

The previous tools namespace is removed with no compatibility alias. Replace its commands with the MCP commands above. Named upstream accounts belong in mcp(..., { accounts: ... }); legacy cli.mcpAccounts user/group selectors are not upstream aliases. Legacy OAuth records are never silently reassigned. Declare an account and copy an exact legacy session explicitly:
Migration refuses an occupied destination and preserves the original record for rollback. Remote validity remains unverified until a live check. See Named MCP connections for configuration and the shared-vault integration contract.

​
Legacy fentaris auth login <mcp>

This legacy API addresses existing downstream-scoped OAuth sessions only. Use fentaris mcp auth connect for named upstream accounts. The command opens the authorization URL, receives the redirect on a loopback listener it owns, and writes the tokens to the project’s encrypted OAuth store.
--as takes user:<id> or shared; omit it for the shared authorization. --print-url and --non-interactive never spawn a browser. --port fixes the loopback redirect port, which pre-registered clients need. --timeout caps the wait for the redirect callback and defaults to 300 seconds, after which the command exits non-zero instead of waiting forever. A running proxy picks up the new tokens without a restart.

​
fentaris auth status [mcp]

List stored upstream OAuth authorizations with their session and expiry. Token values are never printed.

​
fentaris auth logout <mcp>

Delete the stored authorization for one server and session. The next call requires a new login.

​
fentaris auth and fentaris auth keys

auth displays incoming identities and active key counts. auth keys offers an explicit Create/List/Revoke menu in a terminal. Partially specified commands ask only for missing fields; automation and JSON return missing fields and next actions without prompting.
Creation stores only an encrypted verifier hash and intentionally delivers the raw generated key once, marked sensitive. Later inventory shows ID, name, incoming user, creation time, optional expiry, and revocation status. Revoke by ID. Clients send x-fentaris-api-key; configure projectVaultIdentityStrategy to enforce expiry and revocation. The removed auth api-key commands are replaced by named keys.

​
fentaris secrets

Bare secrets and list display reference, source, resolution state, and consumers. Get returns metadata, never the value. Stored/present always leaves remote validity unverified. Offline reads never contact providers. Check returns nonzero for missing, locked, or unresolvable references.
Set uses hidden input or stdin and preserves references/consumers on update. It accepts explicit environment/external source bindings, with --replace-source required for a source change. Raw --value, secret user/group scopes, and unset have been removed. Removing an in-use credential requires an explicit destructive choice; noninteractive commands must supply --force. References/consumers remain for recovery. The project vault uses macOS Keychain when supported, or an explicitly configured FENTARIS_VAULT_KEY/application credential-store adapter. Fentaris never automatically puts an unlock key into project .env. Existing process variables override automatically loaded project .env values. See Project vault and client keys for storage, source adapters, SDK configuration, recovery, and the explicit secrets migrate --mapping <file> --legacy-file <file> [--incoming-keys] migration. Legacy secrets setup/doctor remain available for old manifests; setup requires the original explicit legacy unlock key and does not generate one into .env. Vault requirements direct users to the new command families.

​
fentaris secrets manifest

Generate or validate .fentaris/secrets.manifest.json from credential(...), credentialJson(...), credentialVault(...), and credentialEnv(...) declarations in the project entrypoint. The manifest contains source metadata and Fentaris user API-key counts, but never credential values.
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:
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.
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.