CLI overview & install

The Alfe CLI (@alfe.ai/cli) connects an agent from your own machine or server, runs the local gateway daemon, and manages the agent’s runtime, integrations, and MCP servers. Use this page to install it and look up a command.

Install

npm

npm i @alfe.ai/cli -- -g

pnpm

pnpm add @alfe.ai/cli -g

bun

bun add @alfe.ai/cli -g

The CLI needs Node.js 20.3 or later. Some runtimes need a newer Node.js, and setup tells you when yours does. The command is alfe. Check the version with:

Terminal

alfe --version

Which key the CLI uses

The CLI stores one API key in ~/.alfe/config.toml, and the kind of key decides what works:

• Your login — alfe login in the browser stores a key for you, not for an agent. Use it on your own computer, for example with alfe aws share.
• An agent key — a setup token from the agent’s Overview tab belongs to that agent. alfe setup, memory, and other agent commands need this kind.

The key decides which agent you set up, not the agent you have open in the dashboard. Run alfe whoami to see which one you’re using.

Configuration

Setup and login write ~/.alfe/config.toml for you, so you don’t normally edit it. It holds your API key, the active runtime, and per-runtime workspace settings.

The API endpoint is derived from your API key, so most commands need no extra flags.

To opt out of CLI error reporting, set ALFE_ERROR_REPORTING=0 in the environment or errorReporting = false in the config file.

Commands

The CLI ships these top-level commands:

Command	What it does
alfe login	Authenticate the CLI with your Alfe account.
alfe setup	Connect an agent on this machine.
alfe setup --managed	Run setup without prompts, from environment variables.
alfe doctor	Diagnose configuration, the API key, the daemon, and the runtime.
alfe whoami	Show the current identity.
alfe gateway <cmd>	Manage the local gateway daemon.
alfe runtime switch <runtime>	Move this agent to another runtime.
alfe claude connect	Wire your own Claude Code into Alfe.
alfe integration <cmd>	Install and manage integrations.
alfe mcp <cmd>	Manage MCP servers available to the agent.
alfe aws <cmd>	Use AWS accounts connected to Alfe, or share your AWS session.
alfe gpu <cmd>	Rent GPU instances with your connected Vast.ai account.
alfe remove	Uninstall Alfe integrations and their runtime config.

alfe login

Authenticates the CLI as you. It offers a browser flow or a pasted API key, then stores the resulting key in ~/.alfe/config.toml. A browser login prints a URL and a code, and waits for you to approve it in the dashboard.

Terminal

alfe login

It accepts these options:

• --token <key> — use a pre-issued API key, for CI and headless servers. You can also set the ALFE_API_KEY environment variable.
• --method <browser|api-key> — skip the interactive method picker.
• --no-browser — print the URL instead of opening a browser.
• --force — re-authenticate even if a valid key already exists.
• --gateway <url> — override the API base URL.

alfe whoami

Shows the tenant, agent, key type, runtime, and API endpoint for the stored key. The key itself is shortened.

alfe gateway

Manages the local gateway daemon that keeps the agent connected to Alfe. When the daemon is installed as a system service, start, stop, and restart go through the service manager.

Subcommand	Purpose
start	Start the daemon.
stop	Stop the daemon.
restart	Restart the daemon.
status	Show daemon status.
install	Install the daemon as a system service that starts on boot.
uninstall	Remove the system service.
logs	Tail the daemon logs.
daemon	Run the daemon in the foreground. Service managers use this.

alfe runtime

Switches this agent to another runtime in place. The agent keeps its memory, chat history, connections, and secrets.

Terminal

alfe runtime switch claude-code

The command previews what’s kept and what’s lost, then asks you to confirm. Pass -y or --yes to skip the prompt. See Switch an agent’s runtime.

alfe claude

Wires your own interactive Claude Code into Alfe, so a plain claude session gains Alfe tools and memory. See Connect your Claude Code.

alfe integration

Installs and manages integrations for the connected agent. Alias: alfe int.

Subcommand	Purpose
list	List installed integrations.
search [query]	Search the integration registry.
install <name> [version]	Install an integration from the registry.
configure <name>	Configure an installed integration interactively.
status [name]	Health-check one or all integrations.
remove <name>	Uninstall an integration.

See Integrations for what’s available and how connect flows work.

alfe mcp

Manages the MCP servers the agent can use.

Subcommand	Purpose
list (alias ls)	List registered MCP servers. Add --json for machine-readable output.
add <id>	Register a server. Supports --transport <stdio|sse|streamable-http>, --command, --args, --env, --url, --header, and --owner.
remove <id> (alias rm)	Remove a server. Use --force for entries the CLI or an integration owns.
test <id>	Connect briefly and list the tools a server advertises. Add --timeout <ms>.

See Use MCP servers with your agent.

alfe aws

Works with AWS accounts connected to Alfe.

Subcommand	Purpose
profiles	On an agent, list the AWS CLI profiles it can use. Add --json for machine-readable output.
credentials	Print short-lived credentials for a profile. The AWS CLI calls this through credential_process.
share	On your own computer, share your local AWS session with one agent. Needs alfe login and AWS CLI v2.9 or later.

See Connect an AWS account for the share options, including --watch and --stop.

alfe gpu

Rents GPU instances with the Vast.ai account connected to the agent. Every instance has a hard runtime cap that you set, and it’s destroyed when the cap is reached.

Subcommand	Purpose
search	Search offers, cheapest first. Filter with --gpu, --num-gpus, --max-price, --min-vram, --region, --any-host, and --limit.
launch	Rent an instance. Requires --offer, --image, and --max-hours.
ls (alias list)	List this agent’s instances.
show <instanceId>	Show status, spend, and ready-to-run ssh and scp commands.
logs <instanceId>	Print container logs. Add --tail <n>.
destroy <instanceId>	Destroy an instance now. This stops charges and deletes its data.

See Rent GPUs with Vast.ai for how this works and what it costs.