Documentation

Everything you need to configure, create, and run CLI tools with ShareToolbox.

#Installation

Download ShareToolbox from the landing page and drag it to your Applications folder. On first launch, the app creates the tools directory at ~/.toolbox/tools/ if it doesn't already exist.

Requirements:

• macOS 14.0 (Sonoma) or later
• Apple Silicon or Intel Mac

#Quick Start

1. Download and install ShareToolbox
2. Click "Create with AI" in the toolbar
3. Describe the tool you want in plain English
4. AI generates the config and it appears in the sidebar instantly
5. Fill in the form and hit Run (or Cmd+Return)

#Your First Tool

Click "Create with AI" and type something like:

A tool that checks if a file exists and shows its info using ls

The AI will generate a complete tool config with the right executable, arguments, and flags. It appears in the sidebar immediately — select it, pick a file, and press Run.

You can also use "Add from Folder" to wrap existing scripts, or "Add from GitHub" to import a repo directly. See AI Tool Creation for details.

#Schema Overview

Each tool is defined by a JSON config file placed in ~/.toolbox/tools/. The app watches this directory and automatically loads any .json files it finds.

#Top-Level Fields

#Arguments

Arguments are positional parameters passed to the executable. Each argument object supports:

#Argument Types

#Flags

Flags are CLI options placed before positional arguments in the command. Each flag object supports:

Boolean flags are included in the command only when enabled. String flags pass their value after the flag string.

#Environment Variables

Declare environment variables your tool needs (e.g. API keys). Values are stored securely in the macOS Keychain.

#Full Example

Here's a complete config that demonstrates all features:

{
  "name": "API Caller",
  "icon": "network",
  "description": "Make HTTP requests to any API endpoint",
  "executable": "/usr/bin/curl",
  "arguments": [
    {
      "name": "url",
      "label": "URL",
      "type": "string",
      "placeholder": "https://api.example.com/data",
      "required": true
    },
    {
      "name": "output",
      "label": "Save to File",
      "type": "file",
      "placeholder": "~/Downloads/response.json"
    }
  ],
  "flags": [
    {
      "name": "verbose",
      "label": "Verbose Output",
      "flag": "-v",
      "type": "bool"
    },
    {
      "name": "method",
      "label": "HTTP Method",
      "flag": "-X",
      "type": "string"
    }
  ],
  "environment": [
    {
      "name": "API_TOKEN",
      "label": "API Token"
    }
  ]
}

#Arguments & Flags

ShareToolbox builds commands by placing flags first, followed by positional arguments in the order they appear in your config. For example, given the API Caller config above with verbose enabled and the URL set:

/usr/bin/curl -v https://api.example.com/data

#File & Folder Pickers

Arguments with type file or directory get a native macOS picker button next to the text field. You can either type a path manually or click the button to browse. Tilde (~) is automatically expanded to your home directory.

#Boolean Flags

Boolean flags render as toggle switches. When enabled, the flag string is included in the command. When disabled, it's omitted entirely. This is useful for flags like -v (verbose), -a (all), or --dry-run.

#Environment Variables

When a tool declares an environment array, an "Environment" section appears in the tool form. Each variable shows a secure input field (masked text). A green checkmark appears when a value is stored in the Keychain.

At runtime, ShareToolbox reads each declared variable from the Keychain and injects it into the tool's process environment before launching. Values are also saved before each run to capture any last-minute changes.

#Create with AI: Natural Language

Click "Create with AI" in the toolbar and describe what you want in plain English:

• "Create a tool that resizes images using ImageMagick"
• "Make a tool for converting MP4 to GIF with ffmpeg"
• "Build a tool that runs pylint on a Python project"

Claude AI generates a complete JSON config with the right executable path, arguments, flags, and types. The config is saved to ~/.toolbox/tools/ and appears in the sidebar instantly.

#Add from Folder

Point ShareToolbox to a folder containing scripts or executables. AI analyzes the contents, identifies entry points, and generates a config that maps to the right executable with appropriate arguments.

This is ideal for wrapping existing shell scripts, Python scripts, or any folder-based tooling you already have.

#Add from GitHub URL

Paste a GitHub repository URL and ShareToolbox will:

1. Clone the repo to ~/.toolbox/scripts/<repo-name>/
2. Analyze the codebase to find the main entry point
3. Generate a config pointing to the cloned executable
4. Save the config to ~/.toolbox/tools/

Re-adding the same repo URL updates the existing clone with git pull instead of failing.

#Keychain Integration

ShareToolbox stores all sensitive values (API keys, tokens, passwords) in the native macOS Keychain. Nothing is ever written to plain text files. Each secret is stored under the "Toolbox" service with a composite account key of toolName.varName for unique identification.

#Referencing Secrets

To use secrets in your tool, declare them in the environment array of your JSON config:

{
  "environment": [
    {
      "name": "ANTHROPIC_API_KEY",
      "label": "Anthropic API Key"
    },
    {
      "name": "DATABASE_URL",
      "label": "Database Connection String"
    }
  ]
}

The first time you run the tool, enter the values in the secure input fields. They are saved to the Keychain and automatically loaded on subsequent runs.

#Settings Window

Open the Settings window with Cmd+, to manage all stored secrets in one place. Secrets are grouped by tool name, and you can:

• See which variables are set vs. unconfigured
• Edit values inline via secure input fields
• Delete individual secrets with one click

Only tools that declare environment variables appear in the Settings window.

#Command Building

ShareToolbox constructs the command in this order:

1. Executable path — the executable field from your config
2. Flags — boolean flags (when enabled) and string flags (with their values)
3. Positional arguments — in the order defined in your config

The PATH is automatically augmented with /opt/homebrew/bin and /usr/local/bin so tools installed via Homebrew work out of the box, even though GUI apps typically don't inherit your shell PATH.

#Streaming Output

When a tool runs, its output streams into a terminal-like panel in real time. Standard output (stdout) and standard error (stderr) are displayed with distinct styling so you can quickly tell them apart. The panel shows a running indicator while the process is active and displays the exit code when it completes.

Click the Clear button to reset the output panel between runs.

#Error Handling

ShareToolbox handles errors at several levels:

• Validation — Required fields must be filled before the Run button becomes active
• Process errors — If the executable can't be found or fails to launch, the error is shown in the output panel
• Runtime errors — stderr output is color-coded red for easy identification
• Exit codes — The process exit code is displayed when execution completes, so you can see whether the tool succeeded (0) or failed (non-zero)