Toollist CLI

Toollist CLI is the public command-line client for Toollist. It gives you a fast way to authenticate, upload files, inspect your workspace, and run hosted Toollist tools from scripts, terminals, and agent workflows.

Install

Requires Node.js 18.18 or newer.

Run it without installing anything:

npx toolist-cli@latest --help

Install it globally:

npm install -g toolist-cli
toolist --help

Quick Start

Authenticate with Toollist:

npx toolist-cli@latest login

Inspect the current identity:

npx toolist-cli@latest whoami

Upload a public file:

npx toolist-cli@latest files upload --input ./photo.jpg --public --json

Hosted Environments

Toollist CLI has three built-in hosted environments:

• prod -> https://tooli.st
• test -> https://test.tooli.st
• dev -> http://localhost:3024

If you do not pass any environment flags, the CLI resolves the target in this order:

1. --base-url
2. --env
3. TOOLLIST_ENV
4. saved config active environment
5. prod

--base-url is for self-hosted or custom deployments. Hosted environment selection always uses the canonical Toollist URLs above, even if you previously saved a profile for that environment.

Examples:

npx toolist-cli@latest login --env test
npx toolist-cli@latest whoami --env prod
TOOLIST_ENV=dev npx toolist-cli@latest files upload --input ./photo.jpg
npx toolist-cli@latest tools list --base-url https://self-hosted.example.com --token $TOOLIST_TOKEN

After logging in, commands reuse the saved login automatically. You only need --token when you want to override saved credentials explicitly.

Common Commands

Run a high-level image conversion:

npx toolist-cli@latest image convert --input ./photo.jpg --to webp --compress smallest --sync --wait

Image conversion, resize, and crop commands also support compression presets:

• --compress balanced maps to quality: 75
• --compress small maps to quality: 55
• --compress smallest maps to quality: 35
• --to webp defaults to --compress small when neither --quality nor --compress is provided.
• Explicit --quality takes precedence when both options are provided.

Recommended article image conversion:

npx toolist-cli@latest image convert --input ./demo.png --to webp --compress smallest --sync --wait --output ./demo.webp

Batch conversion:

npx toolist-cli@latest image convert-batch --input-glob './images/*.png' --to webp --compress smallest --wait --output-dir ./images-webp

Remove a watermark from a single image:

npx toolist-cli@latest image remove-watermark --input ./photo.jpg --wait --output ./photo-clean.jpg

Remove the background from a single image:

npx toolist-cli@latest image remove-background --input ./photo.png --wait --output ./photo-background-removed.png

Resize an image and write the derived artifact locally:

npx toolist-cli@latest image resize --input ./photo.jpg --width 1200 --to webp --sync --wait --output ./photo-1200.webp

Crop an image to a bounding box and download the result:

npx toolist-cli@latest image crop --input ./photo.jpg --x 120 --y 80 --width 640 --height 480 --to png --sync --wait --output ./photo-crop.png

Convert a DOCX file into a Markdown bundle:

npx toolist-cli@latest document docx-to-markdown --input ./document.docx --wait --output ./bundle.zip

Convert multiple DOCX files into Markdown bundles:

npx toolist-cli@latest document docx-to-markdown-batch --inputs ./chapter-1.docx ./chapter-2.docx --wait --output ./results.zip

Run a manifest-driven batch:

npx toolist-cli@latest batch run --manifest ./batch.json

List available hosted tools:

npx toolist-cli@latest tools list --env test

Example manifest:

{
  "version": 1,
  "defaults": {
    "concurrency": 2,
    "wait": true,
    "download_outputs": true,
    "output_dir": "./outputs"
  },
  "items": [
    {
      "id": "resize-1",
      "tool_name": "image.resize",
      "input_path": "./photo.jpg",
      "input": {
        "width": 1200,
        "target_mime_type": "image/webp"
      }
    },
    {
      "id": "crop-1",
      "tool_name": "image.crop",
      "input_path": "./photo.jpg",
      "input": {
        "x": 0,
        "y": 0,
        "width": 640,
        "height": 480,
        "target_mime_type": "image/webp"
      }
    }
  ]
}

Development

npm install
npm run lint
npm test
npm run build

After building, the executable is available at dist/cli.js.

Contributing

Issues and pull requests are welcome. Before opening a release-oriented change, make sure you run the local checks above and describe any hosted test validation you performed.

Maintainers should also read:

• Delivery Docs Hub
• One-Page Team Execution Flow
• Maintainer Guide
• Release Handbook

Release

Releases publish to npm through GitHub Actions after the pre-release gate has passed. See docs/release-handbook.md for the maintainer checklist.

Released under the MIT License.