Skip to content

surfaces-and-testing.md

Latest commit

 

History

History
343 lines (243 loc) · 11.8 KB

surfaces-and-testing.md

File metadata and controls

343 lines (243 loc) · 11.8 KB
Raw

InFlow Surfaces And Testing

This guide covers installation and smoke testing for the signed native inflow command-line application, its bundled skills, and its local MCP server. The npm package is a compatibility notice and cannot run commands, start MCP, or manage credentials.

This guide does not cover the separate direct InFlow API MCP server used for account management, policies, approvals, withdrawals, sellers, and users.

Install the native application

Install InFlow before configuring an agent host. Public installation supports Apple Silicon and Intel macOS, Windows x64 and ARM64, and Linux ARM64 and AMD64. On macOS, Homebrew is available:

brew tap inflowpayai/tap
brew install --cask inflow

The hosted shell installer supports macOS, Debian/Ubuntu, and Fedora/RHEL:

curl -fsSL https://inflowcli.ai/install.sh | bash

On Windows PowerShell:

irm https://inflowcli.ai/install.ps1 | iex

On macOS, Linux, or a Git Bash-like Windows environment, the compatibility endpoint delegates to the appropriate platform installer:

curl -fsSL https://inflowcli.ai/cli | bash

Windows users can also install through WinGet:

winget install --id InFlowPayAI.InFlow --exact

Signed Linux ARM64 and AMD64 Debian packages, RPM packages, and standalone archives are published through GitHub Releases. Signed Windows x64 and ARM64 MSI packages install the command-line application and on-demand vault service. For release-operator setup, see the native release guide.

The Windows MSI installs inflow.exe under %ProgramFiles%\InFlow, adds that directory to the system PATH, and registers the demand-start InFlowVault service as NT SERVICE\InFlowVault. Per-user encrypted vaults live under %ProgramData%\InFlow\vaults; uninstall preserves that directory.

Verify the installed executable:

inflow --version
inflow auth status --format json
inflow vault status

Credential vault boundary

OAuth tokens, API keys, and Agent Enrollment Protocol credentials are encrypted in the local InFlow vault. Initialize or unlock it from a human-controlled terminal:

inflow vault unlock

Do not put the PIN or passphrase in an agent prompt, MCP input, command-line flag, environment variable, or redirected standard input. The structured CLI and MCP server deliberately expose no unlock-factor field. When the vault is locked, the agent receives a human-action error; unlock it manually and retry the original request.

Useful lifecycle commands:

inflow vault status
inflow vault policy
inflow vault lock
inflow vault change-passphrase
inflow vault reset

inflow auth logout removes local authentication and vault state after attempting eligible remote cleanup. Application uninstall preserves encrypted vault data. Use the platform-specific purge operation only when the data must also be removed.

Shared MCP configuration

The signed binary contains the CLI, MCP, and daemon entry points. Configure every host to execute that installed binary:

{
  "mcpServers": {
    "inflow": {
      "command": "inflow",
      "args": ["--mcp"]
    }
  }
}

If a graphical host does not inherit the shell PATH, use the absolute path returned by:

command -v inflow

To use the sandbox environment in a host that supports per-server environment variables:

{
  "mcpServers": {
    "inflow": {
      "command": "inflow",
      "args": ["--mcp"],
      "env": {
        "INFLOW_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Do not replace inflow with npx, Node, a repository checkout, or a copied JavaScript bundle. Those paths do not carry the installed application identity required by the vault boundary.

Skills and plugins

The repository contains the agentic-enrollment and agentic-payments skills. A skills-aware host can install them with:

npx skills add inflowpayai/inflow-cli

The repository also contains Claude Code, Cursor, Codex, and generic agent plugin manifests. Each plugin points its MCP entry at inflow --mcp; the signed native application must already be installed on the host.

For an MCP-only host, print a bundled skill body and paste it into that host's instructions:

inflow --skill
inflow --skill agentic-enrollment

On macOS, inflow --skill | pbcopy copies the default payment playbook. Use wl-copy or xclip on Linux and clip on Windows.

Claude Desktop

Plain Claude Desktop does not use the Claude Code plugin manager. Paste the desired skill into project instructions, then add the shared MCP configuration to:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Fully quit and reopen Claude Desktop. Confirm the MCP server starts, then ask it to call auth_status.

Claude Code and local Cowork

Install the plugin from a Claude Code session:

/plugin marketplace add inflowpayai/inflow-cli
/plugin install inflow@inflow

The plugin installs the skill and MCP manifest together. Local Cowork launches the MCP server on the host; do not copy the binary, vault database, or credentials into its Linux guest. Remote Cowork cannot use a local MCP server unless the product provides an explicit host bridge.

After plugin installation, trigger /agentic-payments and ask the host to list InFlow MCP tools. Unlock the vault in a separate host terminal before testing a credential-bearing tool.

Codex and Cursor

Install the repository plugin through the host's plugin browser. Codex discovers .codex-plugin/plugin.json; Cursor discovers .cursor-plugin/marketplace.json. Both ultimately execute the shared inflow --mcp entry.

For a manual Cursor setup, place the shared MCP configuration in ~/.cursor/mcp.json or .cursor/mcp.json, restart Cursor, and confirm the tools panel shows InFlow.

Hermes, Cline, Continue.dev, and raw MCP

These hosts can use the shared MCP configuration if they accept a standard-input/output MCP server. Use the exact configuration shape required by the host, with command set to the installed inflow path and arguments set to ["--mcp"].

For a raw protocol smoke test:

{
  printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
  printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
  printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
} | inflow --mcp

Expected: initialization reports serverInfo.name as inflow, and tools/list returns the installed tool inventory.

What to test

The live CLI is the source of truth for commands, schemas, and MCP tools:

inflow --llms --format json
inflow --llms-full --format json
inflow <command> --schema --format json

For each agent host:

  1. Confirm the installed executable reports the expected version.
  2. Confirm the skill loads when the host supports skills.
  3. Confirm MCP tools/list returns the current inventory.
  4. Confirm auth_status reports locked state without exposing secrets when the vault is locked.
  5. Unlock the vault manually and confirm auth_login reaches a verification URL.
  6. Confirm balances_list or deposit-addresses_list returns structured data after authentication.
  7. Confirm a read-only x402_inspect or mpp_inspect call.
  8. Run a payment only against an approved test endpoint and funded test account.

Do not use direct InFlow API MCP results as evidence for this local CLI-backed MCP surface.

Upgrade

For Homebrew:

brew upgrade --cask inflow

For a hosted installation, rerun the hosted installer. Reinstall or refresh the plugin separately when its skill or manifest changes, then restart the host.

For WinGet:

winget upgrade --id InFlowPayAI.InFlow --exact

The CLI checks the latest GitHub Release with a two-second deadline. Human executions may print an advisory update notice. auth status structured output may include current_version and latest_version. An advisory does not block the current command; VERSION_UNSUPPORTED means the upgrade is mandatory. Set NO_UPDATE_NOTIFIER=1 to disable the advisory check.

Upgrades preserve the encrypted vault but leave it locked after daemon replacement. Unlock it manually before the next credential-bearing request.

Uninstall and purge

Homebrew uninstall:

brew uninstall --cask inflow

Hosted macOS uninstall:

curl -fsSL https://inflowcli.ai/install.sh | bash -s -- --uninstall

Hosted Windows uninstall:

$env:INFLOW_UNINSTALL = '1'
try { irm https://inflowcli.ai/install.ps1 | iex } finally { Remove-Item Env:INFLOW_UNINSTALL }

WinGet uninstall:

winget uninstall --id InFlowPayAI.InFlow --exact

Windows Installer and Linux package uninstall preserve encrypted vault data. Linux install.sh --purge removes the package and system vault data. inflow vault reset is the cross-platform command for intentionally removing local vault state before uninstall.

Troubleshooting

MCP process does not start

On macOS or Linux, run command -v inflow in the same environment as the host. If the graphical host has a different PATH, configure the absolute path. Run inflow --mcp in a terminal and inspect the host's MCP logs.

On Windows, restart the terminal and graphical host after installation so they inherit the updated system PATH. If needed, configure the MCP command with the resolved full path, such as C:\Program Files\InFlow\inflow.exe, and inspect the service with:

Get-Command inflow
Get-Service InFlowVault

MCP tools are present but credential operations fail

Run:

inflow vault status
inflow auth status --format json

If the vault is locked, run inflow vault unlock in a human terminal. Do not add the factor to MCP configuration.

The agent guesses the payment flow

The skill is missing. Refresh the plugin on skill-aware hosts, or paste the output of inflow --skill into the host's instructions.

Environment is wrong

Check inflow auth status --format json. Use --sandbox, --environment sandbox, or INFLOW_ENVIRONMENT=sandbox. Add an env block only when the MCP host supports it.

A custom legacy credential file remains

The signed application deletes the standard legacy plaintext configuration and any path explicitly supplied through --auth or INFLOW_AUTH_FILE. It cannot discover arbitrary paths that are no longer supplied. If an older installation used a custom path, remove that file manually after confirming the signed application is using the encrypted vault. Do not pass the legacy file to another application or attempt to import it into the vault.

Installed binary appears modified or mismatched

Reinstall through the signed platform channel. Do not copy an executable between installations or invoke a development bundle as a substitute. On macOS, verify with codesign --verify --deep --strict; on Windows, inspect the Authenticode signature; on Linux, reinstall through the signed package or repository once the production repository is published.

Get-AuthenticodeSignature "$env:ProgramFiles\InFlow\inflow.exe"

Privacy and security checks

  • Confirm command and MCP output never contains access tokens, refresh tokens, API keys, credentials, or unlock factors.
  • Confirm agent and MCP schemas have no PIN, passphrase, password, secret, or raw authorization input.
  • Confirm locked and unavailable vault states fail closed.
  • Confirm the MCP host launches the installed signed binary, not npm or a development checkout.
  • Confirm update checks contain no credentials and can be disabled with NO_UPDATE_NOTIFIER=1.
  • Confirm reset, logout, uninstall, and purge behavior matches the user's intended data-retention choice.