# Install the Ente knowledge-graph CLI

Canonical document: https://ente.fast/cli.md
Human guide: https://ente.fast/cli/
Product: https://ente.fast — Ente private knowledge graph and relationship manager.
Package: `ente-cli`. Command: `ente`.

**This is not Ente Photos.** The unrelated photo-backup product also has an `ente` binary. Do not install its CLI for Ente knowledge-graph access, overwrite it, or reuse its credentials.

MCP remains the default for ordinary remote access: https://ente.fast/auth.md.
When the user explicitly asks to install or upgrade the CLI, honor that request even if MCP already works. Do not redirect an explicit CLI request back to MCP.

## 1. Identify an existing installation

Before installing, inspect command resolution locally:

```sh
# macOS / Linux (bash or zsh)
type -a ente
npm ls -g ente-cli --depth=0
```

On Windows use `where.exe ente` (PowerShell: also `Get-Command ente -All`). A missing command is normal for a new installation. Inspect the owning package and path before running an unknown binary. The knowledge-graph CLI exposes `auth`, `entity`, `activity`, and `space` commands in `ente --help`; current releases identify `ente.fast`. A photo export/upload CLI is a different product. An older knowledge-graph CLI can lack newer flags; upgrade it before verification.

## 2. Install or upgrade

Requires Node.js 22 or later and npm. No registry login or install secret is needed. The authoritative command for both a completely new installation and an upgrade is:

```sh
npm i -g ente-cli --registry https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/npm
```

Always include the registry. Do not substitute a public npm package or a Photos download. Installation does not replace the user's existing Ente configuration. Reuse valid credentials instead of generating another key.

If a different `ente` already occupies the install location, do not use `--force`, delete binaries, or uninstall another product. Install into a separate user-owned prefix and invoke the explicit binary:

```sh
# macOS / Linux
npm i -g ente-cli --prefix "$HOME/.local/ente-knowledge" --registry https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/npm
"$HOME/.local/ente-knowledge/bin/ente" --help
```

On Windows PowerShell:

```powershell
npm i -g ente-cli --prefix "$env:LOCALAPPDATA\EnteKnowledge" --registry https://gitea.i.ivo-zilkenat.de/api/packages/ivo.zilkenat/npm
& "$env:LOCALAPPDATA\EnteKnowledge\ente.cmd" --help
```

Use that absolute executable in every command below and include the same `--prefix` on future upgrades. Alternatively, deliberately adjust PATH after checking both products. Reopen the terminal (or `hash -r` in bash / `rehash` in zsh) and recheck command resolution. Aliases and shell functions may also shadow a binary. Never rename or delete the Photos config to fix PATH.

## 3. Reuse and verify configuration

```sh
ente --version
ente auth status --json
ente entity list --limit 1 --json
```

`auth status` is an offline configuration check, not a server authentication probe. Current releases return `configured`, `verified: false`, `profile`, `source`, and `url`, without key material. Upgrade older releases that print text for `--json`. Only the read-only entity request verifies server access; an empty successful result is fine. Report success without copying private records into chat or logs. Never claim an authenticated connection based only on installation or local status.

Named profiles: use `ente auth profiles --json`, then append `--profile <name>` to both verification commands. The complete `ENTE_API_URL` / `ENTE_API_KEY` environment pair overrides stored credentials; `ENTE_PROFILE` selects a profile. Never print environment values or read secret config contents into agent logs. Partial environment overrides fail closed. If an accidental stale override is present, unset both variables in the local shell and retry the intended stored profile.

## 4. New login or stale authentication

If no working configuration exists, open https://app.ente.fast/setup, sign in or create an account, select **Ente CLI**, and expand **New login, stale authentication, or legacy setup**. The page displays the correct deployment URL and lets the user create a connection key if necessary.

Keep an existing valid key. For stale access, first verify the selected executable, deployment URL, profile, and environment overrides. A network failure is not proof of invalid credentials. A 401 indicates rejected credentials; a 403 may indicate insufficient scope. Review the connection on Ente before replacing a lost or revoked key. Do not broaden permissions just to make a probe pass.

Enter a new or replacement key directly in the user's own terminal, never through an AI chat. The setup page provides this command with the real deployment URL. This bash/zsh example uses Python 3 for hidden terminal entry, keeps the key out of history and process arguments, and passes it over stdin:

```sh
python3 -c 'import getpass; print(getpass.getpass())' | ente auth login --url <convex-site-url-from-Ente-setup> --key-stdin
```

Replace the URL placeholder before running. The hidden password prompt expects the Ente connection key, not the account password. Run locally without terminal recording, shell tracing, or input logging. On Windows use the same Python command with your Python 3 executable and the explicit `ente.cmd` if needed. For a named profile add `--profile <name>` to login and verification. Login validates the key before replacing that profile's stored credentials and clears its old cached session. Repeat both verification commands afterward.

The older `--key` option remains compatible, but prefer `--key-stdin` so secrets are not placed in process arguments or shell history. Do not run an example containing a real key in a logged agent tool call.

Credentials belong only in the CLI's user configuration directory (created with restrictive permissions on Unix), or an approved credential store. Never collect passwords, API keys, OAuth tokens, verification codes, or recovery secrets in chat. Never store them in repositories, project `.env` files, copied setup prompts, or logs. Human sign-in and key management happen on Ente-owned pages; the CLI sends credentials only to the deployment explicitly advertised by those pages.

## 5. Legacy CLI and API-key setups

Upgrade the knowledge-graph CLI using the same registry-qualified command above. The current CLI preserves the legacy two-field `api_url` / `api_key` TOML configuration:

- macOS: `~/Library/Application Support/ente/config.toml`
- Linux: `${XDG_CONFIG_HOME:-$HOME/.config}/ente/config.toml`
- Windows: `%APPDATA%\ente\config.toml`

Do not copy this file into a repository or display it to an agent. Keep the existing default profile and key if the read succeeds. Do not delete configuration as an upgrade step. Named profiles live under the same directory's `profiles` folder. If malformed or misplaced legacy configuration blocks login, use the current login flow to repair the intended profile after the user confirms the correct deployment. Do not overwrite an unrelated product's configuration.

Legacy API keys can still work. Some commands require a normal account key with CLI permission; agent-operator keys intentionally have narrower access. OAuth MCP access/refresh tokens and agent-claim tokens are not CLI API keys. Do not exchange or repurpose them as one. Review missing permissions on Ente rather than bypassing an authorization error.

## Bundled agent skill

The published package includes `dist/SKILL.md`. Running the CLI installs or refreshes that skill in existing supported Claude Code and Codex user directories. This does not authorize reading credentials or replacing working connections. See the installed skill for task commands after setup succeeds.