Metadata-Version: 2.4
Name: stashapp-cli
Version: 0.1.0
Summary: Command-line client for the Stash GraphQL API
Keywords: stash,graphql,cli
Author: razputingh
Author-email: razputingh <331436478+razputingh@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/razputingh/stashapp-cli
Project-URL: Documentation, https://github.com/razputingh/stashapp-cli/tree/main/docs
Project-URL: Repository, https://github.com/razputingh/stashapp-cli
Project-URL: Issues, https://github.com/razputingh/stashapp-cli/issues
Description-Content-Type: text/markdown

# stashapp-cli

stashapp-cli is a command-line tool for [Stash](https://github.com/stashapp/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](https://jqlang.org/), to read the JSON output in scripts. The
  examples in the guides use it.

## Install

Install stashapp-cli from PyPI with [uv](https://docs.astral.sh/uv/) or
[pipx](https://pipx.pypa.io/). The package is named `stashapp-cli`. The
command it installs is `stashapp-cli`:

```bash
uv tool install stashapp-cli
pipx install stashapp-cli
```

To install the latest code from GitHub, run:

```bash
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.

```bash
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][errors].

## 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:

```bash
stashapp-cli introspect
```

Find a tag by its name or alias:

```bash
stashapp-cli tag find --name hd
```

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

```bash
stashapp-cli tag find-or-create hd
```

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

Add `--apply` to make the change:

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

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

```bash
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.

| Kind | What the command does |
| --- | --- |
| `read` | It never changes Stash. |
| `write` | It changes Stash only with `--apply`. Else it reports the change. |
| `destructive` | It can make a change that you cannot undo. |

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][writes] and
[Updates replace lists][lists].

## Commands

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

| Group | What it does |
| --- | --- |
| [`studio`][studio-cmd] | Get, find, create, and update studios. |
| [`tag`][tag-cmd] | Get, find, create, update, delete, and merge tags. |
| [`group`][group-cmd] | Get, find, create, and update groups, for example films. |
| [`scene`][scene-cmd] | Get, find, and update scenes, and start identify jobs. |
| [`performer`][performer-cmd] | Get, find, create, update, and merge performers. |
| [`scrape`][scrape-cmd] | Get metadata from stash-boxes, scrapers, and URLs. |
| [`scan`, `generate`, `job`][jobs-cmd] | Start scan and generate jobs, and wait for jobs. |
| [`backup`][backup-cmd] | Back up the Stash database. |
| [`stashbox`][stashbox-cmd] | Submit scene fingerprints to a stash-box. |
| [`introspect`, `graphql`][graphql-cmd] | Check the schema, and send your own GraphQL. |

## Documentation

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

## Contributing

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

## License

stashapp-cli is released under the [MIT License][license].

[writes]: docs/usage.md#writes-are-dry-runs-by-default
[lists]: docs/usage.md#updates-replace-lists
[commands]: docs/commands/README.md
[studio-cmd]: docs/commands/studio.md
[tag-cmd]: docs/commands/tag.md
[group-cmd]: docs/commands/group.md
[scene-cmd]: docs/commands/scene.md
[performer-cmd]: docs/commands/performer.md
[scrape-cmd]: docs/commands/scrape.md
[jobs-cmd]: docs/commands/jobs.md
[backup-cmd]: docs/commands/backup.md
[stashbox-cmd]: docs/commands/stashbox.md
[graphql-cmd]: docs/commands/graphql.md
[usage]: docs/usage.md
[guides]: docs/guides/README.md
[errors]: docs/errors.md
[glossary]: docs/glossary.md
[contributing]: CONTRIBUTING.md
[license]: LICENSE
