created_at2021-11-13 20:26:01.177512
updated_at2024-01-12 18:13:53.864401
descriptionImplementation of's API
Eetu Savolainen (Savolae)



Unofficial command line tool and library for using's API.

For the library documentation, see Github Pages.


See the GitHub Releases page for the latest Linux and Windows builds of the command line tool.

You can compile and install the command line tool with Cargo:

cargo install catbox

To use the library in your project, add the repo to your Cargo.toml:

catbox = "*"


Use catbox --help to see usage.

Catbox has the following commands:

  • upload: Upload a file or URL to Catbox.
  • delete: Delete files
  • album: Album commands
  • litter: Upload a temporary file to Litterbox.

If user hash is not given for upload, the files will be uploaded anonymously. Deleting files requires that user hash was given.

The album subcommand has additional subcommands:

  • create: Create a new album
  • delete: Delete an album
  • edit: Edit an album
  • add: Add files to an album
  • remove: Remove files from an album

All album commands except create require an user hash.

You can use --help on any command to see information about its usage.

The basic upload command will work with both local files and URLs to files hosted somewhere else.

Some commands require an account hash to work. This can be supplied using the --user argument or by setting CATBOX_USER_HASH environment value. The explicitly provided argument will be preferred over the environment variable. If the environment variable is set, it will be used even when optional.

All commands print the response from the server, usually a link to the created file or album.

See for more information about the API and for allowed filetypes and content.

Consider donating via to help with server costs.


Upload a file:

catbox upload cute_picture.png

Upload multiple files:

catbox upload *.jpg  # Upload all jpg files
catbox upload image.png file.txt  # Upload image.png and file.txt

Delete a file:

catbox delete abc123.jpg --user 1234567890123456789012345
catbox delete  # Or just 123456.png

Create an album:

catbox album create --title 'My album' --desc 'An excellent album' abc123.jpg def456.png

The user argument is not needed if CATBOX_USER_HASH is found in environment.

Upload a file to Litterbox for 3 days:

catbox litter --time 72h
Commit count: 34

cargo fmt