Swordfish

Swordfish CLI

The Swordfish CLI server is a desktop application that enables file system access and command execution. It's required because browser extensions cannot directly access your local file system.

Installation

npm install -g swordfish-agent

Starting the Server

  1. Navigate to Your Project

    Open a terminal and cd into your project directory.

  2. Start the Server

    Run:

    swordfish

    The server will start on http://localhost:8765 by default.

  3. Verify Connection

    The extension will automatically connect to the server. You should see the current working directory in the extension UI.

What the CLI Server Does

The CLI server provides:

  • File Operations - Read, write, search, and list files
  • Command Execution - Run shell commands (npm, git, etc.)
  • Directory Management - Get/set the current working directory
  • Path Operations - Check if paths exist, resolve relative paths

Working Directory

The CLI server operates relative to the directory where you started it. This means:

  • File paths in the extension are relative to this directory
  • Commands run in this directory's context
  • You can change the directory using the desktop app GUI
💡 Tip

Make sure you start the CLI server in the root of your project, not in a subdirectory. This ensures file paths work correctly.

Desktop App GUI

The desktop app provides a GUI for:

  • Managing the Directory - Change the working directory
  • Viewing Server Logs - See what the server is doing
  • Server Status - Check if the server is running

Security

The CLI server:

  • Only accepts connections from localhost
  • Runs commands in the context of your user account
  • Respects file permissions and system security
⚠️ Important

The CLI server has full access to your file system and can execute commands. Only run it in trusted environments and with projects you trust.

Troubleshooting

Server Won't Start

  • Check if port 8765 is already in use
  • Make sure Node.js is installed and in your PATH
  • Try running swordfish --help to see available options

Extension Can't Connect

  • Verify the server is running on http://localhost:8765
  • Check your firewall settings
  • Try restarting both the server and the extension

File Operations Fail

  • Make sure you're in the correct directory
  • Check file permissions
  • Verify file paths are relative to the working directory