@edgestore/cli

EdgeStore CLI

Manage EdgeStore accounts, projects, and agent setup from the terminal.

Install and log in

npm install --global @edgestore/cli
edgestore --help

Log in through the dashboard, then use init for guided local setup:

edgestore login
edgestore init

init --install selects packages from the application's dependencies. Next.js, Remix/React Router, and TanStack Start receive server and React packages. Astro, Hono, Express, and Fastify receive the server package, plus the React package when React is declared. React-only frontends receive the React package. Already-declared EdgeStore packages are left unchanged.

Use edgestore login --device when a local browser callback is unavailable. Use edgestore login --token or EDGESTORE_TOKEN for automation. Persisted credentials are stored in the operating system credential store and are never written to a plaintext config file.

Application context

Inspect installed EdgeStore versions and local reference paths without logging in:

edgestore --cwd apps/web agent context --json

At an unlinked workspace root with child packages, it lists them and returns exit code 2. Select an application with --cwd, or use --cwd . to select the root. The JSON uses schema version 1 and includes installed versions, reference paths, and skill and MCP configuration status.

Yarn Plug'n'Play resolution is not supported. When a PnP loader is present, declared packages report unsupported-resolution and compatibility is unresolved. Use the project's Yarn environment to inspect installed versions.

Agent setup and updates

edgestore agent setup --client codex --dry-run --json
edgestore agent setup --client codex --yes
edgestore agent status --client codex --json
edgestore agent update --client codex --yes

Use claude for Claude Code or cursor for Cursor. Setup installs the skill and configures MCP for the project. --skills-only leaves MCP settings untouched; --global installs for all projects.

Client	Skill directory
Codex	.agents/skills
Claude Code	.claude/skills
Cursor	.cursor/skills

These paths are relative to the Git or package root, or your home for global setup. The CLI reports existing global skills without installing a duplicate.

The skill comes from the installed CLI release. status compares against that copy, not an online release. setup leaves older installed copies in place; use update to replace them. Neither command upgrades application packages.

Keep .edgestore/skill-assets.json with the installed skill. Updates stop on user edits, extra files, or symlinks, even with --yes. If a write fails, the error lists files already changed. Restart the client or open a new task after updating.

The repository plugin bundles the same skill and the hosted MCP connection for Codex, Claude Code, and Cursor. If you use the plugin, skip agent setup and mcp setup and sign in through your client's MCP controls. The CLI leaves skills installed through other tools untouched.

Direct MCP configuration

Configure the hosted connection independently of skills or plugins:

edgestore mcp setup --client codex --dry-run --json
edgestore mcp setup --client codex --yes
edgestore mcp status --client codex --json
edgestore mcp remove --client codex --yes

Use codex, claude for Claude Code, or cursor. Setup writes to the Git root, or the package root outside Git. Use --cwd to select the project and --global for user configuration. Automated writes require --yes.

Client	Project configuration	User configuration
Codex	.codex/config.toml	$CODEX_HOME/config.toml or ~/.codex/config.toml
Claude Code	.mcp.json	~/.claude.json
Cursor	.cursor/mcp.json	~/.cursor/mcp.json

Setup preserves existing connections, unrelated settings, and JSONC comments.

Keep .edgestore/agent-assets.json with the config. Global setup stores this metadata in the CLI's user config directory. Removal requires an unchanged entry created by this CLI. --yes does not override user edits or name conflicts. If a write fails, the error lists files already changed.

Setup uses https://api.edgestore.dev/mcp; --api-url does not change it. status checks configuration only. Sign in and grant permissions through your client. Codex also requires project trust for project-local configuration.

Client documentation: Codex MCP, Claude Code MCP, and Cursor MCP.

Local diagnostics

edgestore --cwd apps/web doctor --offline --json
edgestore --cwd apps/api doctor --json

--offline skips credentials and network access. Normal doctor uses an existing credential for read-only API checks. It does not log in or refresh credentials.

Checks return pass, warn, fail, or skip. A failure sets exit code 1. Doctor checks adapter and provider imports, CORS, and env file locations without running application code or returning env values. It cannot verify route mounting, provider ancestry, custom env loading, or remote bucket mappings.

The output lists skipped checks and scan limits.

Project keys and tokens

Interactive commands display a new secret once. Automated key creation, key rotation, and token creation require --output to a gitignored backend env file. JSON returns metadata and delivery status, without secretKey or secret. Scripts that read those fields must switch to file delivery.

Automated project create requires --without-key. Create its key separately with project key create --output. Clipboard-only delivery is not supported for automated commands.

edgestore project list
edgestore bucket create publicFiles --type file --public
edgestore file upload ./logo.png --bucket publicFiles
edgestore project key create <basePath> --name local --output .env.local

init reuses its configured env destination, or detects existing env files before choosing .env.local. For an ambiguous noninteractive destination, pass --output explicitly after checking which file the backend loads.

Workspaces

In a monorepo, run commands from the application package or select it explicitly with --cwd:

edgestore --cwd apps/web init
edgestore --cwd apps/web bucket list

Each workspace package keeps its own .edgestore/config.json. From a configured monorepo root, the CLI uses the root configuration. From an unconfigured root, it uses the only configured package automatically or asks which package to use when more than one is configured. Automation should pass --cwd or an explicit --project when the choice is ambiguous.

Output

Use --json for structured output and --plain for commands with one natural value. Both modes are non-interactive, so pass required choices explicitly and use --yes when a command requires confirmation. Run edgestore completion bash, zsh, or fish to configure shell completion.