better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-docker-management.md

@@ -1,298 +0,0 @@
----
-title: "Docker Management — Manage Docker containers, images, volumes, and Compose"
-sidebar_label: "Docker Management"
-description: "Manage Docker containers, images, volumes, and Compose"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Docker Management
-
-Manage Docker containers, images, volumes, and Compose.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/docker-management` |
-| Path | `optional-skills/devops\docker-management` |
-| Version | `1.0.0` |
-| Author | sprmn24 |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `docker`, `containers`, `devops`, `infrastructure`, `compose`, `images`, `volumes`, `networks`, `debugging` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Docker Management
-
-Manage Docker containers, images, volumes, networks, and Compose stacks using standard Docker CLI commands. No additional dependencies beyond Docker itself.
-
-## When to Use
-
-- Run, stop, restart, remove, or inspect containers
-- Build, pull, push, tag, or clean up Docker images
-- Work with Docker Compose (multi-service stacks)
-- Manage volumes or networks
-- Debug a crashing container or analyze logs
-- Check Docker disk usage or free up space
-- Review or optimize a Dockerfile
-
-## Prerequisites
-
-- Docker Engine installed and running
-- User added to the `docker` group (or use `sudo`)
-- Docker Compose v2 (included with modern Docker installations)
-
-Quick check:
-
-```bash
-docker --version && docker compose version
-```
-
-## Quick Reference
-
-| Task | Command |
-|------|---------|
-| Run container (background) | `docker run -d --name NAME IMAGE` |
-| Stop + remove | `docker stop NAME && docker rm NAME` |
-| View logs (follow) | `docker logs --tail 50 -f NAME` |
-| Shell into container | `docker exec -it NAME /bin/sh` |
-| List all containers | `docker ps -a` |
-| Build image | `docker build -t TAG .` |
-| Compose up | `docker compose up -d` |
-| Compose down | `docker compose down` |
-| Disk usage | `docker system df` |
-| Cleanup dangling | `docker image prune && docker container prune` |
-
-## Procedure
-
-### 1. Identify the domain
-
-Figure out which area the request falls into:
-
-- **Container lifecycle** → run, stop, start, restart, rm, pause/unpause
-- **Container interaction** → exec, cp, logs, inspect, stats
-- **Image management** → build, pull, push, tag, rmi, save/load
-- **Docker Compose** → up, down, ps, logs, exec, build, config
-- **Volumes & networks** → create, inspect, rm, prune, connect
-- **Troubleshooting** → log analysis, exit codes, resource issues
-
-### 2. Container operations
-
-**Run a new container:**
-
-```bash
-# Detached service with port mapping
-docker run -d --name web -p 8080:80 nginx
-
-# With environment variables
-docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16
-
-# With persistent data (named volume)
-docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16
-
-# For development (bind mount source code)
-docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app
-
-# Interactive debugging (auto-remove on exit)
-docker run -it --rm ubuntu:22.04 /bin/bash
-
-# With resource limits and restart policy
-docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app
-```
-
-Key flags: `-d` detached, `-it` interactive+tty, `--rm` auto-remove, `-p` port (host:container), `-e` env var, `-v` volume, `--name` name, `--restart` restart policy.
-
-**Manage running containers:**
-
-```bash
-docker ps                        # running containers
-docker ps -a                     # all (including stopped)
-docker stop NAME                 # graceful stop
-docker start NAME                # start stopped container
-docker restart NAME              # stop + start
-docker rm NAME                   # remove stopped container
-docker rm -f NAME                # force remove running container
-docker container prune           # remove ALL stopped containers
-```
-
-**Interact with containers:**
-
-```bash
-docker exec -it NAME /bin/sh          # shell access (use /bin/bash if available)
-docker exec NAME env                   # view environment variables
-docker exec -u root NAME apt update    # run as specific user
-docker logs --tail 100 -f NAME         # follow last 100 lines
-docker logs --since 2h NAME            # logs from last 2 hours
-docker cp NAME:/path/file ./local      # copy file from container
-docker cp ./file NAME:/path/           # copy file to container
-docker inspect NAME                    # full container details (JSON)
-docker stats --no-stream               # resource usage snapshot
-docker top NAME                        # running processes
-```
-
-### 3. Image management
-
-```bash
-# Build
-docker build -t my-app:latest .
-docker build -t my-app:prod -f Dockerfile.prod .
-docker build --no-cache -t my-app .              # clean rebuild
-DOCKER_BUILDKIT=1 docker build -t my-app .       # faster with BuildKit
-
-# Pull and push
-docker pull node:20-alpine
-docker login ghcr.io
-docker tag my-app:latest registry/my-app:v1.0
-docker push registry/my-app:v1.0
-
-# Inspect
-docker images                          # list local images
-docker history IMAGE                   # see layers
-docker inspect IMAGE                   # full details
-
-# Cleanup
-docker image prune                     # remove dangling (untagged) images
-docker image prune -a                  # remove ALL unused images (careful!)
-docker image prune -a --filter "until=168h"   # unused images older than 7 days
-```
-
-### 4. Docker Compose
-
-```bash
-# Start/stop
-docker compose up -d                   # start all services detached
-docker compose up -d --build           # rebuild images before starting
-docker compose down                    # stop and remove containers
-docker compose down -v                 # also remove volumes (DESTROYS DATA)
-
-# Monitoring
-docker compose ps                      # list services
-docker compose logs -f api             # follow logs for specific service
-docker compose logs --tail 50          # last 50 lines all services
-
-# Interaction
-docker compose exec api /bin/sh        # shell into running service
-docker compose run --rm api npm test   # one-off command (new container)
-docker compose restart api             # restart specific service
-
-# Validation
-docker compose config                  # validate and view resolved config
-```
-
-**Minimal compose.yml example:**
-
-```yaml
-services:
-  api:
-    build: .
-    ports:
-      - "3000:3000"
-    environment:
-      # Password comes from the POSTGRES_PASSWORD secret, not the URL
-      - DATABASE_URL=postgres://mydb_user@db:5432/mydb
-    depends_on:
-      db:
-        condition: service_healthy
-
-  db:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_USER: user
-      POSTGRES_PASSWORD: pass
-      POSTGRES_DB: mydb
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U user"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  pgdata:
-```
-
-### 5. Volumes and networks
-
-```bash
-# Volumes
-docker volume ls                       # list volumes
-docker volume create mydata            # create named volume
-docker volume inspect mydata           # details (mount point, etc.)
-docker volume rm mydata                # remove (fails if in use)
-docker volume prune                    # remove unused volumes
-
-# Networks
-docker network ls                      # list networks
-docker network create mynet            # create bridge network
-docker network inspect mynet           # details (connected containers)
-docker network connect mynet NAME      # attach container to network
-docker network disconnect mynet NAME   # detach container
-docker network rm mynet                # remove network
-docker network prune                   # remove unused networks
-```
-
-### 6. Disk usage and cleanup
-
-Always start with a diagnostic before cleaning:
-
-```bash
-# Check what's using space
-docker system df                       # summary
-docker system df -v                    # detailed breakdown
-
-# Targeted cleanup (safe)
-docker container prune                 # stopped containers
-docker image prune                     # dangling images
-docker volume prune                    # unused volumes
-docker network prune                   # unused networks
-
-# Aggressive cleanup (confirm with user first!)
-docker system prune                    # containers + images + networks
-docker system prune -a                 # also unused images
-docker system prune -a --volumes       # EVERYTHING — named volumes too
-```
-
-**Warning:** Never run `docker system prune -a --volumes` without confirming with the user. This removes named volumes with potentially important data.
-
-## Pitfalls
-
-| Problem | Cause | Fix |
-|---------|-------|-----|
-| Container exits immediately | Main process finished or crashed | Check `docker logs NAME`, try `docker run -it --entrypoint /bin/sh IMAGE` |
-| "port is already allocated" | Another process using that port | `docker ps` or `lsof -i :PORT` to find it |
-| "no space left on device" | Docker disk full | `docker system df` then targeted prune |
-| Can't connect to container | App binds to 127.0.0.1 inside container | App must bind to `0.0.0.0`, check `-p` mapping |
-| Permission denied on volume | UID/GID mismatch host vs container | Use `--user $(id -u):$(id -g)` or fix permissions |
-| Compose services can't reach each other | Wrong network or service name | Services use service name as hostname, check `docker compose config` |
-| Build cache not working | Layer order wrong in Dockerfile | Put rarely-changing layers first (deps before source code) |
-| Image too large | No multi-stage build, no .dockerignore | Use multi-stage builds, add `.dockerignore` |
-
-## Verification
-
-After any Docker operation, verify the result:
-
-- **Container started?** → `docker ps` (check status is "Up")
-- **Logs clean?** → `docker logs --tail 20 NAME` (no errors)
-- **Port accessible?** → `curl -s http://localhost:PORT` or `docker port NAME`
-- **Image built?** → `docker images | grep TAG`
-- **Compose stack healthy?** → `docker compose ps` (all services "running" or "healthy")
-- **Disk freed?** → `docker system df` (compare before/after)
-
-## Dockerfile Optimization Tips
-
-When reviewing or creating a Dockerfile, suggest these improvements:
-
-1. **Multi-stage builds** — separate build environment from runtime to reduce final image size
-2. **Layer ordering** — put dependencies before source code so changes don't invalidate cached layers
-3. **Combine RUN commands** — fewer layers, smaller image
-4. **Use .dockerignore** — exclude `node_modules`, `.git`, `__pycache__`, etc.
-5. **Pin base image versions** — `node:20-alpine` not `node:latest`
-6. **Run as non-root** — add `USER` instruction for security
-7. **Use slim/alpine bases** — `python:3.12-slim` not `python:3.12`

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-hermes-s6-container-supervision.md

@@ -1,198 +0,0 @@
----
-title: "Hermes S6 Container Supervision — Modify or debug s6 services in the Hermes Docker image"
-sidebar_label: "Hermes S6 Container Supervision"
-description: "Modify or debug s6 services in the Hermes Docker image"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Hermes S6 Container Supervision
-
-Modify or debug s6 services in the Hermes Docker image.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/hermes-s6-container-supervision` |
-| Path | `optional-skills/devops\hermes-s6-container-supervision` |
-| Version | `1.0.0` |
-| Author | Hermes Agent |
-| License | MIT |
-| Platforms | linux |
-| Tags | `docker`, `s6`, `supervision`, `gateway`, `profiles` |
-| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# Hermes s6-overlay Container Supervision
-
-## When to use this skill
-
-Load this skill when you're working on:
-- Adding or removing a static service in the Hermes Docker image (something that should be supervised at every container start, like the dashboard)
-- Diagnosing why a per-profile gateway isn't starting, restarting, or surviving `docker restart`
-- Understanding why the container's CMD is `/opt/hermes/docker/main-wrapper.sh` and how leading-dash args reach the user's program
-- Modifying `cont-init.d` boot scripts (UID remap, volume seeding, profile reconciliation)
-- Changing the rendered run-script for per-profile gateways (Phase 4)
-
-If you're just running the Hermes Agent and want to use Docker, see `website/docs/user-guide/docker.md` instead.
-
-## Architecture at a glance
-
-<!-- ascii-guard-ignore -->
-```
-/init                                  ← PID 1 (s6-overlay v3.2.3.0)
-├── cont-init.d                        ← oneshot setup, runs as root
-│   ├── 01-hermes-setup                ← docker/stage2-hook.sh
-│   │   ├── UID/GID remap
-│   │   ├── chown /opt/data
-│   │   ├── chown /opt/data/profiles (every boot)
-│   │   ├── seed .env / config.yaml / SOUL.md
-│   │   └── skills_sync.py
-│   └── 02-reconcile-profiles          ← hermes_cli.container_boot
-│       ├── chown /run/service (hermes-writable for runtime register)
-│       └── walk $HERMES_HOME/profiles/<name>/gateway_state.json
-│           → recreate /run/service/gateway-<name>/
-│           → auto-start only those with prior_state == "running"
-│
-├── s6-rc.d (static services, in /etc/s6-overlay/s6-rc.d/)
-│   ├── main-hermes/run                ← exec sleep infinity (no-op slot)
-│   └── dashboard/run                  ← if HERMES_DASHBOARD=1, runs `hermes dashboard`
-│
-├── /run/service (s6-svscan watches; tmpfs)
-│   ├── gateway-coder/                 ← runtime-registered per-profile
-│   │   ├── type        ("longrun")
-│   │   ├── run         ("#!/command/with-contenv sh ... exec s6-setuidgid hermes hermes -p coder gateway run")
-│   │   ├── down        (marker — present means "registered but don't auto-start")
-│   │   └── log/run     (s6-log → $HERMES_HOME/logs/gateways/coder/current)
-│   └── ...
-│
-└── CMD ("main program")               ← /opt/hermes/docker/main-wrapper.sh
-    └── routes user args: bare exec | hermes subcommand | hermes (no args)
-        — exec'd by /init with stdin/stdout/stderr inherited (TTY for --tui)
-```
-<!-- ascii-guard-ignore-end -->
-
-## Key files
-
-| Path | Role |
-|---|---|
-| `Dockerfile` | s6-overlay install + cont-init.d wiring + `ENTRYPOINT ["/opt/hermes/docker/entrypoint-dispatch.sh"]` |
-| `docker/entrypoint-dispatch.sh` | PID-1 dispatcher: exec's `/init` + main-wrapper when the image owns PID 1; on wrapped runtimes (Fly Machines, `docker run --init`) falls back to stage2-hook + main-wrapper directly, restoring the s6 helper PATH first (#38349). |
-| `docker/stage2-hook.sh` | The "old entrypoint logic" — UID remap, chown, seed, skills sync. Runs as cont-init.d/01-hermes-setup. |
-| `docker/cont-init.d/02-reconcile-profiles` | Calls `hermes_cli.container_boot` on every boot to restore profile gateway slots from the persistent volume. |
-| `docker/main-wrapper.sh` | The container's CMD. Routes user args, drops to hermes via `s6-setuidgid`, exec's the chosen program. |
-| `docker/s6-rc.d/main-hermes/run` | No-op `sleep infinity` — slot exists so the s6-rc user bundle is valid; main hermes runs as the CMD, not as a supervised service. |
-| `docker/s6-rc.d/dashboard/run` | Conditional service — `exec sleep infinity` unless `HERMES_DASHBOARD` is truthy. |
-| `docker/entrypoint.sh` | Back-compat shim that `exec`s the stage2 hook. External scripts that hard-coded the old entrypoint path still work. |
-| `hermes_cli/service_manager.py` | `S6ServiceManager`: `register_profile_gateway`, `unregister_profile_gateway`, `start/stop/restart/is_running`, `list_profile_gateways`. |
-| `hermes_cli/container_boot.py` | `reconcile_profile_gateways()` — walks persistent profiles, regenerates s6 slots, emits `container-boot.log`. |
-| `hermes_cli/gateway.py::_dispatch_via_service_manager_if_s6` | Intercepts `hermes gateway start/stop/restart` and routes to s6 when running in a container. |
-
-## Why Architecture B (CMD as main program, not s6-supervised)
-
-The original plan (v1–v3) called for main hermes to run as a supervised s6-rc service. Two real s6-overlay v3 mechanics blocked that:
-
-1. **cont-init.d scripts receive no CMD args** — so the stage2 hook can't parse `docker run <image> chat -q "hi"` to set `HERMES_ARGS` for a service `run` script to consume.
-2. **`/run/s6/basedir/bin/halt` does NOT propagate the exit code** written to `/run/s6-linux-init-container-results/exitcode`. Containers always exit 143 (SIGTERM) regardless. Confirmed by skarnet (s6 author) in [issue #477](https://github.com/just-containers/s6-overlay/issues/477): _"if you want a container shutdown, you need to either have your CMD exit, or, if you have no CMD, write the container exit code you want then call halt"_.
-
-So we use the s6-overlay-native CMD pattern via the dispatcher: `ENTRYPOINT ["/opt/hermes/docker/entrypoint-dispatch.sh"]`, which under PID 1 exec's `/init /opt/hermes/docker/main-wrapper.sh "$@"`. The wrapper is prepended to user args automatically — so `docker run <image> --version` becomes `/init main-wrapper.sh --version`, and `--version` doesn't get intercepted by /init's POSIX shell. The wrapper drops to hermes via `s6-setuidgid`, then exec's the chosen program. The program's exit code becomes the container exit code, exactly matching the pre-s6 tini contract. When the entrypoint is NOT PID 1 (Fly Machines, `docker run --init`), the dispatcher skips `/init` entirely (it would abort with `can only run as pid 1`), restores the s6 helper PATH, runs stage2-hook.sh, and exec's main-wrapper.sh directly — no supervised services on that path (#38349).
-
-Trade-off: main hermes is unsupervised under s6. That exactly matches its behavior under tini (the pre-s6 image). Dashboard supervision is the only **new** guarantee — and per-profile gateways under `/run/service/` get full supervision.
-
-## Quick recipes
-
-### Verify s6 is PID 1 in a running container
-
-```sh
-docker exec <c> sh -c 'cat /proc/1/comm; readlink /proc/1/exe'
-# Expect: s6-svscan or init / /package/admin/s6/.../s6-svscan
-```
-
-### Inspect a profile gateway service
-
-```sh
-# /command/ isn't on docker-exec PATH — use absolute path
-docker exec <c> /command/s6-svstat /run/service/gateway-<name>
-# "up (pid …) … seconds"            → running
-# "down (exitcode N) … seconds, normally up, want up, …" → s6 wants it up but the process keeps exiting (crash loop)
-# "down … normally up, ready …"     → user stopped it
-```
-
-### Bring a service up/down manually
-
-```sh
-docker exec <c> /command/s6-svc -u /run/service/gateway-<name>   # up
-docker exec <c> /command/s6-svc -d /run/service/gateway-<name>   # down
-docker exec <c> /command/s6-svc -t /run/service/gateway-<name>   # SIGTERM (restart)
-```
-
-### Watch the cont-init reconciler log
-
-```sh
-docker exec <c> tail -n 50 /opt/data/logs/container-boot.log
-# 2026-05-21T06:18:05+0000 profile=coder prior_state=running action=started
-# 2026-05-21T06:18:05+0000 profile=writer prior_state=stopped action=registered
-```
-
-### Add a new static service
-
-1. Create `docker/s6-rc.d/<name>/type` with `longrun\n` and `docker/s6-rc.d/<name>/run` (use `#!/command/with-contenv sh` + `# shellcheck shell=sh`).
-2. Drop to hermes via `s6-setuidgid hermes` at the top of run (unless you specifically need root).
-3. Create empty `docker/s6-rc.d/<name>/dependencies.d/base` so it waits for the base bundle.
-4. Create empty `docker/s6-rc.d/user/contents.d/<name>` so it joins the user bundle.
-5. The `COPY docker/s6-rc.d/` in the Dockerfile picks it up automatically — no other changes.
-
-### Change the per-profile gateway run command
-
-Edit `S6ServiceManager._render_run_script` in `hermes_cli/service_manager.py`. The function is also called by `hermes_cli/container_boot.py::_register_service` during boot reconciliation, so it's the single source of truth. Update the corresponding assertion in `tests/hermes_cli/test_service_manager.py::test_s6_register_creates_service_dir_and_triggers_scan`.
-
-### Run the docker test harness
-
-```sh
-docker build -t hermes-agent-harness:latest .
-HERMES_TEST_IMAGE=hermes-agent-harness:latest scripts/run_tests.sh tests/docker/ -v
-# Expect 19 passed, 0 xfailed against the s6 image
-```
-
-The harness lives in `tests/docker/` and skips when Docker isn't available. The per-test timeout is bumped to 180s (see `tests/docker/conftest.py`).
-
-## Common pitfalls
-
-### "command not found" via `docker exec`
-
-`/command/` (where s6-overlay puts its binaries) is on PATH only for processes spawned by the supervision tree — services, cont-init.d, main-wrapper.sh. `docker exec <c> s6-svstat …` will fail with "command not found"; always use the absolute path `/command/s6-svstat`. The `hermes` binary works because the Dockerfile adds `/opt/hermes/.venv/bin` to the runtime `ENV PATH`.
-
-### Profile directory ownership
-
-The cont-init reconciler runs as hermes (`s6-setuidgid hermes` in `02-reconcile-profiles`). If a profile dir ends up root-owned (e.g. because `docker exec <c> hermes profile create …` ran as root by default), the reconciler can't read SOUL.md and fails with `PermissionError`. Mitigation: `stage2-hook.sh` chowns `$HERMES_HOME/profiles` to hermes on **every** boot, idempotently. Don't remove that block.
-
-### Files written by `docker exec` are root-owned
-
-`docker exec` defaults to root. Either pass `--user hermes` or rely on the stage2 chown sweep next reboot. Don't write files under `$HERMES_HOME/profiles/<name>/` as root manually — the next reconcile pass will sweep them but in-flight operations may hit perm errors.
-
-### Service slot exists but s6-svstat says "s6-supervise not running"
-
-The service directory is on tmpfs and was wiped on container restart. Either the cont-init reconciler hasn't run yet (give it a moment after `docker restart`) or it failed. Check `docker logs <c> | grep '02-reconcile'`.
-
-### Gateway starts then immediately exits (`down (exitcode 1)` in svstat)
-
-Most likely the profile has no model or auth configured. The service slot is correct — the gateway itself is unconfigured. Run `hermes -p <profile> setup` first. The s6 supervisor will keep restarting it; that's the desired behavior (when you fix the config, the next attempt succeeds and stays up).
-
-### Reconciler skipped a profile
-
-The reconciler keys on the **presence of `SOUL.md`** as the "real profile" marker. `hermes profile create` always seeds it. If a profile dir is missing SOUL.md (stray directory, partial restore, backup-in-progress), the reconciler skips it intentionally. Add a `SOUL.md` (even empty) to opt back in.
-
-### "Help, the container exits 143!"
-
-Check whether something is invoking `s6-svscanctl -t` or `/run/s6/basedir/bin/halt` — both cause /init to begin stage 3 shutdown but return 143 (SIGTERM) rather than the desired exit code. This was the Phase 2 architecture pivot from A to B. For container shutdown with a real exit code, you must let the CMD (main-wrapper.sh) exit normally; do **not** try to control exit from a finish script.
-
-## Related skills
-
-- `hermes-agent-dev`: General hermes-agent codebase navigation
-- `hermes-tool-quirks`: Specific Hermes-tool workarounds (sed/grep/etc.) — load when debugging the s6 stack's interaction with hermes built-in tools.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-inference-sh-cli.md

@@ -1,173 +0,0 @@
----
-title: "Inference Sh Cli — Run 150+ AI apps (image, video, LLM) via inference.sh CLI"
-sidebar_label: "Inference Sh Cli"
-description: "Run 150+ AI apps (image, video, LLM) via inference.sh CLI"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Inference Sh Cli
-
-Run 150+ AI apps (image, video, LLM) via inference.sh CLI.
-
-## Skill metadata
-
-| | |
-|---|---|
-| Source | Optional — install with `hermes skills install official/devops/inference-sh-cli` |
-| Path | `optional-skills/devops\inference-sh-cli` |
-| Version | `1.0.0` |
-| Author | okaris |
-| License | MIT |
-| Platforms | linux, macos, windows |
-| Tags | `AI`, `image-generation`, `video`, `LLM`, `search`, `inference`, `FLUX`, `Veo`, `Claude` |
-
-## Reference: full SKILL.md
-
-:::info
-The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
-:::
-
-# inference.sh CLI
-
-Run 150+ AI apps in the cloud with a simple CLI. No GPU required.
-
-All commands use the **terminal tool** to run `infsh` commands.
-
-## When to Use
-
-- User asks to generate images (FLUX, Reve, Seedream, Grok, Gemini image)
-- User asks to generate video (Veo, Wan, Seedance, OmniHuman)
-- User asks about inference.sh or infsh
-- User wants to run AI apps without managing individual provider APIs
-- User asks for AI-powered search (Tavily, Exa)
-- User needs avatar/lipsync generation
-
-## Prerequisites
-
-The `infsh` CLI must be installed and authenticated. Check with:
-
-```bash
-infsh me
-```
-
-If not installed:
-
-```bash
-curl -fsSL https://cli.inference.sh | sh
-infsh login
-```
-
-See `references/authentication.md` for full setup details.
-
-## Workflow
-
-### 1. Always Search First
-
-Never guess app names — always search to find the correct app ID:
-
-```bash
-infsh app list --search flux
-infsh app list --search video
-infsh app list --search image
-```
-
-### 2. Run an App
-
-Use the exact app ID from the search results. Always use `--json` for machine-readable output:
-
-```bash
-infsh app run <app-id> --input '{"prompt": "your prompt here"}' --json
-```
-
-### 3. Parse the Output
-
-The JSON output contains URLs to generated media. Present these to the user with `MEDIA:<url>` for inline display.
-
-## Common Commands
-
-### Image Generation
-
-```bash
-# Search for image apps
-infsh app list --search image
-
-# FLUX Dev with LoRA
-infsh app run falai/flux-dev-lora --input '{"prompt": "sunset over mountains", "num_images": 1}' --json
-
-# Gemini image generation
-infsh app run google/gemini-2-5-flash-image --input '{"prompt": "futuristic city", "num_images": 1}' --json
-
-# Seedream (ByteDance)
-infsh app run bytedance/seedream-5-lite --input '{"prompt": "nature scene"}' --json
-
-# Grok Imagine (xAI)
-infsh app run xai/grok-imagine-image --input '{"prompt": "abstract art"}' --json
-```
-
-### Video Generation
-
-```bash
-# Search for video apps
-infsh app list --search video
-
-# Veo 3.1 (Google)
-infsh app run google/veo-3-1-fast --input '{"prompt": "drone shot of coastline"}' --json
-
-# Seedance (ByteDance)
-infsh app run bytedance/seedance-1-5-pro --input '{"prompt": "dancing figure", "resolution": "1080p"}' --json
-
-# Wan 2.5
-infsh app run falai/wan-2-5 --input '{"prompt": "person walking through city"}' --json
-```
-
-### Local File Uploads
-
-The CLI automatically uploads local files when you provide a path:
-
-```bash
-# Upscale a local image
-infsh app run falai/topaz-image-upscaler --input '{"image": "/path/to/photo.jpg", "upscale_factor": 2}' --json
-
-# Image-to-video from local file
-infsh app run falai/wan-2-5-i2v --input '{"image": "/path/to/image.png", "prompt": "make it move"}' --json
-
-# Avatar with audio
-infsh app run bytedance/omnihuman-1-5 --input '{"audio": "/path/to/audio.mp3", "image": "/path/to/face.jpg"}' --json
-```
-
-### Search & Research
-
-```bash
-infsh app list --search search
-infsh app run tavily/tavily-search --input '{"query": "latest AI news"}' --json
-infsh app run exa/exa-search --input '{"query": "machine learning papers"}' --json
-```
-
-### Other Categories
-
-```bash
-# 3D generation
-infsh app list --search 3d
-
-# Audio / TTS
-infsh app list --search tts
-
-# Twitter/X automation
-infsh app list --search twitter
-```
-
-## Pitfalls
-
-1. **Never guess app IDs** — always run `infsh app list --search <term>` first. App IDs change and new apps are added frequently.
-2. **Always use `--json`** — raw output is hard to parse. The `--json` flag gives structured output with URLs.
-3. **Check authentication** — if commands fail with auth errors, run `infsh login` or verify `INFSH_API_KEY` is set.
-4. **Long-running apps** — video generation can take 30-120 seconds. The terminal tool timeout should be sufficient, but warn the user it may take a moment.
-5. **Input format** — the `--input` flag takes a JSON string. Make sure to properly escape quotes.
-
-## Reference Docs
-
-- `references/authentication.md` — Setup, login, API keys
-- `references/app-discovery.md` — Searching and browsing the app catalog
-- `references/running-apps.md` — Running apps, input formats, output handling
-- `references/cli-reference.md` — Complete CLI command reference