stashapp-cli

stashapp-cli is a command-line tool for Stash, the self-hosted organizer for your media library. It reads and changes your Stash library through the GraphQL API of Stash. Each command prints JSON, so you can use stashapp-cli in shell scripts and with tools such as jq.

stashapp-cli is not part of the Stash project. The Stash developers do not make or support it.

What it does

• Find, create, and update studios, tags, groups, scenes, and performers.
• Merge duplicate tags and performers, and delete tags. A dry run first reports what the change will remove.
• Scrape metadata from stash-boxes and installed scrapers.
• Start scan, generate, and identify jobs, and wait for them to end.
• Back up the Stash database, and submit scene fingerprints to a stash-box.
• Send a GraphQL query or mutation that you write.

A stash-box is a shared database of scene and performer metadata, such as StashDB.

Requirements

• Python 3.13 or later.
• A Stash server and an API key for it. stashapp-cli is tested with Stash v0.31.1.
• Optional: jq, to read the JSON output in scripts. The examples in the guides use it.

Install

Install stashapp-cli from PyPI with uv or pipx. The package is named stashapp-cli. The command it installs is stashapp-cli:

uv tool install stashapp-cli
pipx install stashapp-cli

To install the latest code from GitHub, run:

uv tool install git+https://github.com/razputingh/stashapp-cli

Connect to Stash

stashapp-cli reads two environment variables. It has no credential flags or credential files.

export STASH_URL=http://localhost:9999
export STASH_API_KEY=<key>

STASH_URL is the base URL of your Stash server. You make an API key in Stash under Settings > Security > Authentication. If a variable is not set, the command stops with exit status 4. For the other exit statuses, read Errors and exit statuses.

Quick start

Make sure that your Stash server has every name that stashapp-cli uses. Run this command before the first write to a server, and after you upgrade Stash:

stashapp-cli introspect

Find a tag by its name or alias:

stashapp-cli tag find --name hd

Make the tag if it does not exist. Without --apply, the command only reports what it would send:

stashapp-cli tag find-or-create hd

{"applied": false, "operation": "tagCreate", "input": {"name": "hd"}}

Add --apply to make the change:

stashapp-cli tag find-or-create hd --apply

Each command has a --help output with its options and examples:

stashapp-cli --help
stashapp-cli tag --help
stashapp-cli tag merge --help

Changes are dry runs by default

Each command has one of three kinds. The --help output of a command states its kind.

A destructive change needs both --apply and --force. You can put --apply anywhere in the command. Put --force after the command name, for example stashapp-cli tag merge --destination 3 --source 7 --apply --force.

Before you merge or delete, back up the Stash database with stashapp-cli backup --apply.

Do not use --input to add one tag, URL, or alias. A list in --input replaces the whole list in Stash, so the other values are removed. Use the add and remove options instead, for example stashapp-cli scene update 812 --add-tag-id 55.

For the full rules, read Writes are dry runs by default and Updates replace lists.

Commands

Each command is a group followed by an action, for example tag merge. The command reference has a table of all commands and their kinds.

Documentation

• Usage: global options, input values, find filters, dry runs, and list updates.
• Command reference: the behavior of each command.
• Guides: step-by-step tasks, such as how to merge duplicate tags.
• Errors and exit statuses: the JSON error object, the error codes, and the exit statuses.
• Glossary: the terms that these documents use.

Contributing

Bug reports and pull requests are welcome. Read CONTRIBUTING.md for how to run the tests and how to add a command.

License

stashapp-cli is released under the MIT License.