| name | shimmy-tool-textual |
| description | Guidance for using, changing, testing, and troubleshooting the Textual developer CLI shim in this repository, including local image builds, TTY behavior, and Textual app diagnostics. |
Textual Shim
Use this skill when working with shims/textual, its local image, its tests, its docs, or Textual CLI usage through Shimmy.
Files
- Kind dispatcher:
../../../shims/textual
- Version shim:
../../../shims/textual_8_2
- Local image:
../../../images/textual_8_2/Containerfile
- User docs:
../../../docs/shims/textual.md
- Tests:
../../../scripts/test-shimmy.sh
- Installer:
../../../scripts/install-shimmy.sh
- README:
../../../README.md
- Contributor guidance:
../../../CONTRIBUTING.md
- Shared prompt:
../../../docs/prompt-shimmy-project.md
Installed Workflow
When this skill is installed outside the Shimmy source checkout, do not rely on the repo-relative Files paths above. Prefer activated commands such as <tool> --version, inspect selected profile state with shimmy status --format manifest, and use SHIMMY_PROFILE_ACTIVE=upstream <tool> --version when validating the upstream profile. Use repo-local paths such as ./shims/<tool> only when intentionally editing or testing source files in the Shimmy checkout.
Current Behavior
- Default image: locally built
localhost/shimmy-textual-8_2:<context-hash>-<platform>
- Image override:
SHIMMY_TEXTUAL_IMAGE
- Build override:
SHIMMY_TEXTUAL_IMAGE_BUILD=always
- Pull override for image overrides:
SHIMMY_TEXTUAL_IMAGE_PULL=always
- Base image override:
SHIMMY_TEXTUAL_BASE_IMAGE
- Textual version override:
SHIMMY_TEXTUAL_VERSION
- Default base image:
python:3.13-slim-bookworm
- Runtime mode: TTY only when stdin and stdout are terminals
- Mount:
$PWD to /work:rw
- Platform: shared Podman helper resolves
linux/amd64 on Linux and linux/arm64 on macOS
Change Rules
- Keep package installation inside
../../../images/textual_8_2/Containerfile, not the kind dispatcher.
- Preserve TTY detection; Textual apps often need a terminal, while scripted help checks should remain clean.
- Use
SHIMMY_TEXTUAL_IMAGE only as a full runtime image override; local build args apply only to Shimmy-built images.
- Treat
textual run and textual serve as interactive or potentially long-running commands.
- If a Shimmy wrapper fails because of Podman reachability, sandboxing, or AI Agent approval symptoms, follow the
shimmy-escalation workflow before using a non-shim fallback.
- Update the runtime shim, local image, docs, tests, installer behavior, and README together when behavior changes.
Validation
- Direct smoke:
./shims/textual --help
- Diagnostics smoke:
./shims/textual diagnose when environment details are useful and output size is acceptable.
Learning Guidance
- Capture Textual-specific lessons here when they affect TTY behavior, local image builds, app execution, browser serving, diagnostics, or Python base image choice.
- Promote reusable Shimmy design lessons to
../shimmy-create-tool/SKILL.md under Learning Guidance.
