<!-- Generated by scripts/generate-agent-docs.mjs. Edit the generator or agentConnectionData.ts. -->

# FavStash CLI

The npm package **@sketric/favstash-mcp** installs two commands: **favstash** for authentication, setup, and diagnostics; **favstash-mcp** for the local stdio MCP bridge. These are different parts of the same installation.

The bridge gives a local agent access to the hosted FavStash tools and can upload local files before forwarding a tool call. It is not a separate FavStash backend.

## Install and sign in

Recommended for Codex and Claude Code on a local computer with Node.js 20+. Check the registry before using the new commands:

```sh
npm view @sketric/favstash-mcp version
```

Browser OAuth and the `favstash` command require **0.4.0+**. If npm reports an older version or cannot be reached, use the [remote OAuth alternative](https://www.favstash.app/mcp.md) and describe CLI setup as pending. Do not run commands that an older package does not provide.

For Codex:

```sh
npm install -g @sketric/favstash-mcp@latest
favstash auth login
favstash setup --agent codex
favstash doctor
```

For Claude Code, the commands are the same except:

```sh
favstash setup --agent claude-code
```

Complete sign-in and consent in the browser. Reload the owning agent after adding the bridge. Then ask:

```text
Use FavStash's get_stash_summary tool once with no filters. Report whether it succeeded and the returned counts. Zero counts are valid. Do not modify any data.
```

Zero counts are valid. `doctor` verifies the full authenticated handshake, tool schemas, and one count-only read. The host still needs its own read-only verification after reload. Do not publish a post as a connection test.

## One prompt

```text
Install FavStash in this agent by following https://www.favstash.app/INSTALL_FOR_AGENTS.md; you may configure only the FavStash MCP connection, request permission if required, complete browser sign-in with me, and verify a read-only tool call before reporting success.
```

The setup helper uses the installed host CLI and adds only the `favstash` entry. It pins the bridge to this installation’s absolute Node and script paths, so use a stable global installation, not a temporary npx cache. Existing entries are preserved; inspect and save an older entry before manually migrating it. Do not replace an entire host config file. If Node is moved or upgraded to another installation path, rerun setup and review the migration instructions.

## Commands

| Command | Purpose |
| --- | --- |
| `favstash auth login` | Browser OAuth with PKCE; approve access yourself |
| `favstash auth login --no-browser` | Print the sign-in URL instead of opening it |
| `favstash auth status` | Redacted local session state; not a live authorization check |
| `favstash auth logout` | Revoke the session and remove local credentials |
| `favstash setup --agent codex` | Configure Codex with the local bridge |
| `favstash setup --agent claude-code` | Configure Claude Code at user scope |
| `favstash setup --agent codex --dry-run` | Preview configuration without changing it |
| `favstash doctor` | Check the full handshake, hosted schemas, and a count-only read |
| `favstash tools` | Print the local tool catalogue as JSON, without credentials |
| `favstash mcp` / `favstash-mcp` | Start the bridge over stdin/stdout |

Results are JSON on stdout. Instructions and errors use stderr. Exit 0 is success, 1 is a command/authentication failure, and doctor exits 2 on a schema mismatch. Check `--help` for the installed version’s options.

## Credentials and headless environments

The default uses the OS credential store for an encryption key and an encrypted session file under `~/.config/favstash` (or `XDG_CONFIG_HOME/favstash`). Tokens refresh automatically. Multiple agent processes share a lock so refresh-token rotation is serialized.

If the OS store is unavailable, unlock or configure it. Only on a private machine, explicitly choose `favstash auth login --credential-store file`; this uses a private local file rather than OS-backed encryption. POSIX directory/file modes are 700/600; on Windows, use a private user profile and appropriate filesystem ACLs. There is no silent fallback.

The browser must reach the CLI’s `127.0.0.1` callback. `--no-browser` does not turn this into a device-code flow. SSH, containers, and cloud agents need a reachable callback, a host-managed OAuth connection, or a securely supplied API key. They cannot silently configure a separate computer.

`FAVSTASH_API_KEY` takes precedence over OAuth for unattended jobs. Set it through local secret storage, never in a chat, committed config, or command history. `FAVSTASH_MCP_URL` selects another trusted endpoint; `FAVSTASH_CONFIG_DIR` selects an isolated credential directory. The setup helper passes the selected endpoint and directory to the bridge.

Logout retains local credentials if server revocation fails, so it can be retried. `--local-only` explicitly forgets local credentials without revoking remote access. It does not unset an API key supplied by the environment.

## Local media and discovery

The bridge advertises the hosted tools with local-media extensions. For `create_social_post` / `update_social_post`, use `media: [{ localPath: "/absolute/path/file.mp4" }]` or the same shape on a target. For `import_post_media`, use `path` or `files`. Inspect `favstash tools` for the exact schema before calling. Use an explicit media kind where required by the current schema. Remote MCP clients use server-fetchable HTTPS URLs instead.

Local validation runs before upload. The bridge imports the file into FavStash media storage, substitutes the resulting HTTPS reference, and forwards the original operation. Publishing still needs the user’s explicit instruction. Provider credentials stay on FavStash’s backend.

## Updates and optional skills

```sh
npm install -g @sketric/favstash-mcp@latest
favstash doctor
```

Restart the agent after updating. Package versions use SemVer independently from web/mobile releases; generated contracts and release checks prevent silent schema drift. API keys and the `favstash-mcp` executable remain supported.

An optional [FavStash workflow skill](https://www.favstash.app/skills/favstash/SKILL.md) teaches discovery, read-before-write, and media handling. Ask your agent to install it with its usual skill installer. It is also included in the npm package. The skill does not connect or authenticate an account.

[Remote MCP](https://www.favstash.app/mcp) · [API](https://www.favstash.app/api) · [Tool reference](https://www.favstash.app/docs/tools-reference) · [npm](https://www.npmjs.com/package/@sketric/favstash-mcp)