CLI Tool

How to install and use the ffhub CLI to run FFmpeg tasks from your terminal.

The FFHub CLI lets you run FFmpeg tasks directly from your terminal. Local files are automatically uploaded to the cloud for processing.

Prerequisites

You need Node.js 18 or newer installed. Check with:

node --version

If Node isn't installed, grab it from nodejs.org (LTS version is fine).

Installation

Install globally so you can type ffhub from anywhere in your terminal:

npm install -g ffhub

The -g flag means "global" — installs the command to your system PATH instead of a local node_modules folder. Verify it worked:

ffhub help

You should see a list of commands. If the shell says command not found: ffhub, see Troubleshooting below.

Upgrading

npm install -g ffhub@latest

Without installing (`npx`)

If you'd rather not install globally, every command in this doc works with npx ffhub instead of ffhub — npm downloads the latest version on demand:

npx ffhub "ffmpeg -i input.mp4 -c:v libx264 output.mp4"

A bit slower on first run (downloads the package), but no global install.

Configuration

Set your API key using the CLI:

ffhub config YOUR_API_KEY

Or use an environment variable:

export FFHUB_API_KEY=YOUR_API_KEY

Usage Examples

Transcode a video

ffhub "ffmpeg -i input.mov -c:v libx264 -preset fast output.mp4"

Compress a video

ffhub "ffmpeg -i input.mp4 -c:v libx264 -crf 28 output.mp4"

Extract audio

ffhub "ffmpeg -i video.mp4 -vn -c:a libmp3lame audio.mp3"

When the input file is a local path, the CLI automatically uploads it before running the command. Once the task completes, the output file is downloaded to your current directory.

Commands Reference

Command	Description
`ffhub [args]`	Create and run an FFmpeg task
`ffhub whoami`	Show current user info
`ffhub list`	List recent tasks
`ffhub status <task_id>`	Check task status
`ffhub config <api_key>`	Save API key to config
`ffhub help`	Show help message

Troubleshooting

`command not found: ffhub`

After npm install -g, the ffhub binary lives in your npm global bin folder, but that folder needs to be in $PATH. Check:

npm prefix -g       # e.g. /usr/local
echo $PATH | tr ':' '\n' | grep -i bin

The first command shows where npm installs global packages. Confirm <that path>/bin appears in the second command's output. If it doesn't, add this line to your shell config (~/.zshrc, ~/.bashrc, etc.):

export PATH="$(npm prefix -g)/bin:$PATH"

Restart your terminal, then ffhub help should work.

Permission errors on `npm install -g`

If you see EACCES errors, your npm global folder needs sudo. Either run with sudo npm install -g ffhub, or (better) configure npm to use a user-writable folder — see npm docs on fixing permissions.