stashapp-cli 0.1.0__tar.gz

stashapp_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 razputingh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stashapp_cli-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+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

stashapp_cli-0.1.0/README.md

@@ -0,0 +1,184 @@
+# 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

stashapp_cli-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "stashapp-cli"
+version = "0.1.0"
+description = "Command-line client for the Stash GraphQL API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "stash",
+    "graphql",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[[project.authors]]
+name = "razputingh"
+email = "331436478+razputingh@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/razputingh/stashapp-cli"
+Documentation = "https://github.com/razputingh/stashapp-cli/tree/main/docs"
+Repository = "https://github.com/razputingh/stashapp-cli"
+Issues = "https://github.com/razputingh/stashapp-cli/issues"
+
+[project.scripts]
+stashapp-cli = "stashapp_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.9",
+    "ty>=0.0.84",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+src = ["src"]
+exclude = ["*.md"]

stashapp_cli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "stashapp-cli"
+version = "0.1.0"
+description = "Command-line client for the Stash GraphQL API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "razputingh", email = "331436478+razputingh@users.noreply.github.com" }
+]
+keywords = ["stash", "graphql", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/razputingh/stashapp-cli"
+Documentation = "https://github.com/razputingh/stashapp-cli/tree/main/docs"
+Repository = "https://github.com/razputingh/stashapp-cli"
+Issues = "https://github.com/razputingh/stashapp-cli/issues"
+
+[project.scripts]
+stashapp-cli = "stashapp_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.9",
+    "ty>=0.0.84",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py313"
+src = ["src"]
+exclude = ["*.md"]

stashapp_cli-0.1.0/src/stashapp_cli/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from stashapp-cli!"

stashapp_cli-0.1.0/src/stashapp_cli/cli.py

@@ -0,0 +1,149 @@
+"""stashapp-cli: inspect and modify Stash's GraphQL entities directly.
+
+Layers: a raw `graphql` escape hatch, generic per-resource `find`/`get`/
+`create`/`update` commands, and named platform-quirk commands (`tag
+find-or-create`, `scrape group-url`/`scene-url`). Every mutating command is
+gated by the global `--apply` flag (dry-run by default); destructive commands
+(`performer merge`, and raw GraphQL *Destroy/*Delete/*Merge, ...) additionally
+require `--force`. Results print as JSON on stdout; human-facing status and
+errors print to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.metadata
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+
+from . import commands, core
+from .commands._common import add_examples, positive_seconds
+
+
+def _package_version() -> str:
+    """Return installed metadata, with a source-tree fallback for development."""
+    try:
+        return importlib.metadata.version("stashapp-cli")
+    except importlib.metadata.PackageNotFoundError:
+        pyproject = Path(__file__).parents[2] / "pyproject.toml"
+        try:
+            import tomllib
+
+            return tomllib.loads(pyproject.read_text())["project"]["version"]
+        except (OSError, KeyError, tomllib.TOMLDecodeError):
+            return "unknown"
+
+
+def _emit_error(error: core.CliError, json_errors: bool) -> None:
+    if json_errors:
+        core.output(
+            {"error": {"code": error.code, "message": str(error), **error.details}}
+        )
+    else:
+        print(str(error), file=sys.stderr)
+
+
+def _normalize_apply(argv: list[str]) -> list[str]:
+    """Normalize global arguments that argparse cannot otherwise disambiguate."""
+    normalized = list(argv)
+    for index, value in enumerate(normalized[:-1]):
+        if value == "--timeout" and normalized[index + 1].lower() in {
+            "-inf",
+            "-infinity",
+        }:
+            normalized[index : index + 2] = [f"--timeout={normalized[index + 1]}"]
+            break
+    if normalized.count("--apply") != 1:
+        return normalized
+    index = normalized.index("--apply")
+    if index == 0:
+        return normalized
+    return ["--apply", *normalized[:index], *normalized[index + 1 :]]
+
+
+# --- entrypoint ------------------------------------------------------------
+
+
+def iter_leaf_commands(
+    parser: argparse.ArgumentParser, path: tuple[str, ...] = ()
+) -> Iterator[tuple[tuple[str, ...], argparse.ArgumentParser]]:
+    """Yield `(path, parser)` for every leaf command below `parser`."""
+    subparsers = [
+        action
+        for action in parser._actions
+        if isinstance(action, argparse._SubParsersAction)
+    ]
+    if not subparsers:
+        yield path, parser
+        return
+    for action in subparsers:
+        for name, child in action.choices.items():
+            yield from iter_leaf_commands(child, (*path, name))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="stashapp-cli", description=__doc__)
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help=(
+            "Perform mutating commands instead of reporting a dry run "
+            "(default: dry-run; inert on read-only commands)."
+        ),
+    )
+    parser.add_argument(
+        "--json-errors",
+        action="store_true",
+        help="Write expected failures as one JSON error envelope on stdout.",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=positive_seconds,
+        default=core.DEFAULT_TIMEOUT,
+        metavar="SECONDS",
+        help="Maximum seconds for each Stash request (default: 30).",
+    )
+    parser.add_argument("--version", action="version", version=_package_version())
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for module in commands.COMMAND_MODULES:
+        module.register(subparsers)
+    add_examples(
+        parser,
+        "export STASH_URL=http://localhost:9999; export STASH_API_KEY",
+        "stashapp-cli studio find --name ExampleStudio",
+        'stashapp-cli group create --input \'{"name": "Film"}\'',
+        "stashapp-cli group create --input @group.json --apply",
+        "stashapp-cli --json-errors --timeout 5 scene get 1",
+    )
+    parser.epilog = (parser.epilog or "") + (
+        "\n\nExit statuses: 0 success; 1 runtime or GraphQL failure; "
+        "2 usage or invalid input (including destructive_mutation: a destructive\n"
+        "command sent with --apply but without --force); "
+        "3 Stash endpoint returned HTTP 404; "
+        "4 missing credential or authentication failure."
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(
+        _normalize_apply(list(argv))
+        if argv is not None
+        else _normalize_apply(sys.argv[1:])
+    )
+    try:
+        with core.request_timeout(args.timeout):
+            result = args.func(args)
+    except core.CliError as error:
+        _emit_error(error, args.json_errors)
+        sys.exit(error.exit_code)
+    except Exception as error:  # noqa: BLE001
+        _emit_error(core.CliError(f"Unexpected error: {error}", 1), args.json_errors)
+        sys.exit(1)
+    core.output(result)
+
+
+if __name__ == "__main__":
+    main()