{"_id":"@3a2dev/ansi-tui","name":"@3a2dev/ansi-tui","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@3a2dev/ansi-tui","version":"0.1.0","description":"Ansible Terminal User Interface","type":"module","author":{"name":"3A2DEV"},"packageManager":"npm@11.12.1","repository":{"type":"git","url":"git+https://github.com/3A2DEV/ansi-tui.git"},"homepage":"https://github.com/3A2DEV/ansi-tui#readme","bugs":{"url":"https://github.com/3A2DEV/ansi-tui/issues"},"publishConfig":{"access":"public"},"bin":{"ansi-tui":"dist/index.js"},"scripts":{"build":"tsup","dev":"tsup --watch","start":"node dist/index.js","typecheck":"tsc --noEmit","test":"vitest run","test:core":"vitest run tests/core","test:tools":"vitest run tests/tools","test:components":"vitest run tests/components","test:screens":"vitest run tests/screens","test:hooks":"vitest run tests/hooks","test:package":"vitest run tests/package","test:watch":"vitest","lint":"eslint src --ext .ts,.tsx","pack:check":"npm pack --dry-run","verify":"npm run typecheck && npm run lint && npm test && npm run build","prepack":"npm run build","changelog:draft":"towncrier build --draft --version $(node -p \"require('./package.json').version\")","changelog":"towncrier build --version $(node -p \"require('./package.json').version\") --date $(date +%Y-%m-%d)"},"dependencies":{"chalk":"^5.0.0","env-paths":"^3.0.0","execa":"^8.0.0","ink":"^5.0.0","ink-select-input":"^6.0.0","ink-spinner":"^5.0.0","ink-table":"^3.0.0","ink-text-input":"^6.0.0","react":"^18.0.0","strip-ansi":"^7.0.0","uuid":"^10.0.0","which":"^4.0.0"},"devDependencies":{"@types/node":"^25.5.0","@types/react":"^18.0.0","@types/uuid":"^10.0.0","@types/which":"^3.0.0","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.0.0","ink-testing-library":"^3.0.0","tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^4.1.4"},"engines":{"node":">=18.0.0"},"keywords":["ansible","tui","cli","devops","automation"],"license":"MIT","_id":"@3a2dev/ansi-tui@0.1.0","gitHead":"305172ce0afe301a47a4aaa707f8cbd58665b3bb","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-cKurtWTjJPD9h8LvvRsY5qK87YE6xQm+HThsZI96oj+C2qloO56ehOAOFz22IRg3jd70My/nQgUfdZ9ixdIXtw==","shasum":"9d8bb534c9156dd0b7e9ca8cbc9a8f94666bb3ed","tarball":"https://registry.npmjs.org/@3a2dev/ansi-tui/-/ansi-tui-0.1.0.tgz","fileCount":7,"unpackedSize":767189,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@3a2dev%2fansi-tui@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDJZiV7SBddrj382UU1Tb7RU8aKfaDYhtDq5ih70jNwqQIgcIl+OdF6RjCGhmjgNPI8TIWT+9RL4Q+wkrcFq6e9F8Q="}]},"_npmUser":{"name":"nomakcooper","email":"marco.X0178421@gmail.com"},"directories":{},"maintainers":[{"name":"nomakcooper","email":"marco.X0178421@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ansi-tui_0.1.0_1776120766760_0.9381073431815736"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-13T22:52:46.664Z","0.1.0":"2026-04-13T22:52:46.899Z","modified":"2026-04-13T22:52:47.621Z"},"maintainers":[{"name":"nomakcooper","email":"marco.X0178421@gmail.com"}],"description":"Ansible Terminal User Interface","homepage":"https://github.com/3A2DEV/ansi-tui#readme","keywords":["ansible","tui","cli","devops","automation"],"repository":{"type":"git","url":"git+https://github.com/3A2DEV/ansi-tui.git"},"author":{"name":"3A2DEV"},"bugs":{"url":"https://github.com/3A2DEV/ansi-tui/issues"},"license":"MIT","readme":"\n\n\n\n\n\n\n\n\n\n\n
\n \n
\n\n`ansi-tui` wraps common day-to-day Ansible workflows in a guided Ink-based terminal interface. It keeps the exact command line visible, remembers working context per session, streams execution output live, and records active-session runs as structured jobs with logs.\n\nInteractive screens currently exist for `ansible-playbook`, `ansible-galaxy`, `ansible-vault`, `ansible-inventory`, `ansible-doc`, `ansible-config`, `ansible-lint`, `ansible-builder`, `ansible-creator`, `ansible-test`, and `ansible-console`. Runtime detection also reports broader tool availability, including `ansible-pull` and `ansible-community`, but those tools are not yet first-class interactive screens.\n\n\n\n## Highlights\n\n- Full-terminal shell with a static gradient banner, grouped sidebar, dashboard panels, and compact footer command strip\n- Sidebar accordion sub-navigation for tool actions, with direct jump into the form phase\n- Consistent 4-phase workflow for tool screens: action select -> parameter form -> command preview -> execute\n- Session-aware forms that pre-fill inventory, vault, environment, tags, working directory, and other context\n- Session management with create, select, edit, delete, and safe active-session cleanup\n- Jobs screen with recorded executions, exit status, duration, session name, target extraction, detail view, and deletion\n- Live output viewer with scroll, pause/resume, running spinner, elapsed time, and long-output clipping inside the frame\n- Runtime dashboard showing ansible-core, Python, Jinja, PyYAML, config file, collection path, and tool availability\n- Theme system with `Cyan`, `Blue`, `White`, `Gray`, `Yellow`, `Violet`, `Red`, and `Neon`\n- Proxy-aware execution for enterprise environments\n- Color-friendly execution defaults plus OSC 8 hyperlink stripping for cleaner terminal rendering\n- Offline-friendly install flow via `npm pack` and `install.sh --local`\n\n## Full Functionality\n\n### Shell And Navigation\n\n- Full-screen workstation shell anchored to the top of the terminal\n- Grouped sidebar with `WORKSPACE` and `MANAGE` sections\n- Accordion sub-navigation for tool actions\n- Compact footer with active screen context\n- Theme cycling from the keyboard\n\n### Dashboard\n\n- `Session` panel with icon-led rows for name, path, inventory, vault, tags, and notes\n- `Runtime` panel with version chips and config/collections paths\n- `Health & Tool Matrix` panel with a static gradient coverage bar and availability matrix\n- `Workspace Notes` panel with quick operator guidance\n\n### Session Management\n\n- Create sessions with a 2-step flow: name, directory\n- Edit sessions with a 2-step flow: name, directory\n- Delete sessions with explicit confirmation\n- Activate a saved session from the session list\n- Keyboard-driven saved-session list with `Enter`, `n`, `e`, `d`, and `Esc`\n- Safe clearing of the active-session pointer when the active session is deleted\n\n### Tool Workflow Engine\n\n- Shared 4-phase flow across tool screens\n- Direct tool launch from sidebar sub-actions into the form phase\n- Command preview before execution\n- Live command execution with streaming output\n\n### Live Output And Jobs\n\n- Scrollable output panel\n- Pause/resume auto-scroll\n- Wrapped or plain-text output modes depending on tool needs\n- Automatic job recording for active-session runs\n- Automatic per-run log file creation\n- Jobs list with status badges, timestamps, duration, session names, and derived targets\n- Job detail view with metadata and output log\n- Job deletion that also removes the associated log file when present\n- Automatic pruning of old log files on startup\n\n### Enterprise And Runtime Behavior\n\n- Proxy-aware environment merging\n- Forced color-friendly execution defaults for Ansible output\n- OSC 8 hyperlink stripping for safer terminal rendering\n- Blank-line preservation in streamed command output\n- Runtime/tool detection for ansible-core, Python, Jinja, PyYAML, config path, and broader Ansible tool availability\n\n### Supported Interactive Tool Screens\n\n- `ansible-playbook`\n - actions: `run`, `check`, `diff`, `syntax-check`, `list-hosts`, `list-tasks`, `list-tags`\n- `ansible-galaxy`\n - actions: `role install`, `role list`, `role remove`, `role init`, `role search`, `role info`, `role import`, `role delete`, `role setup`, `collection install`, `collection list`, `collection init`, `collection build`, `collection publish`, `collection download`, `collection verify`\n- `ansible-vault`\n - actions: `create`, `encrypt`, `decrypt`, `view`, `edit`, `rekey`, `encrypt_string`\n- `ansible-inventory`\n - actions: `list`, `host`, `graph`\n- `ansible-doc`\n - actions: `lookup`, `list`, `list_files`, `metadata-dump`\n- `ansible-config`\n - actions: `list`, `dump`, `view`, `init`, `validate`\n- `ansible-lint`\n - actions: `run`, `list-rules`, `list-tags`, `list-profiles`\n- `ansible-builder`\n - actions: `build`, `create`, `introspect`\n- `ansible-creator`\n - actions: `init collection`, `init playbook`, `init execution_env`, `add resource`, `add plugin`\n- `ansible-test`\n - actions: `units`, `integration`, `sanity`, `coverage`, `env`, `shell`, `network-integration`, `windows-integration`\n- `ansible-console`\n - actions: `start`\n\n### Management Views\n\n- `Jobs`\n- `Sessions`\n\nThe runtime/tool matrix also detects broader tooling availability including `ansible`, `ansible-pull`, and `ansible-community`. Those tools are reported in the runtime view, but `ansible-pull` and `ansible-community` are not yet exposed as first-class interactive screens.\n\n## Requirements\n\n- Node.js `18+`\n- A modern terminal with color support\n- Ansible tooling is optional, but the app is most useful when `ansible-core` and related binaries are installed\n\n## Install\n\n### From npm\n\n```bash\nnpm install -g @3a2dev/ansi-tui\nansi-tui\n```\n\n### Run without installing\n\n```bash\nnpx @3a2dev/ansi-tui\n```\n\n### Via the install script\n\n```bash\n./install.sh\n```\n\nThis installs to `~/.local/bin/ansi-tui` by default.\n\n### Offline or air-gapped install\n\nBuild a tarball on a connected machine:\n\n```bash\nnpm pack\n```\n\nInstall it on the target machine:\n\n```bash\n./install.sh --local ./3a2dev-ansi-tui-0.1.0.tgz\n```\n\nQuick local package smoke check:\n\n```bash\nnpm pack\n./install.sh --local ./3a2dev-ansi-tui-0.1.0.tgz\n~/.local/bin/ansi-tui --help\n```\n\n## Usage\n\n```bash\nansi-tui\n```\n\nPackage-level CLI helpers:\n\n```bash\nansi-tui --help\nansi-tui --version\n```\n\nOn launch you get:\n\n- a top shell with session and runtime metadata\n- a left navigation rail grouped into `WORKSPACE` and `MANAGE`\n- a dashboard with session, runtime, health/tool matrix, and workspace notes panels\n- a footer with the active screen context and global shortcuts\n\n## How Tool Screens Work\n\nEvery workflow screen follows the same pattern:\n\n1. Select an action.\n2. Fill in parameters from the generated schema.\n3. Review the exact command before execution.\n4. Run it and inspect the live output inside the app.\n\nExecution behavior:\n\n- forms pre-fill from the active session where possible\n- validation failures stay in the UI instead of throwing\n- non-zero exit codes are treated as normal command results\n- runs executed with an active session are written to the jobs history and their output logs are saved automatically\n- launching without an interactive TTY prints a usage-oriented error instead of trying to render the TUI\n\n## Keyboard Shortcuts\n\n\n\n> Use `CTRL + F` to brwose files and directories.\n\n## Sessions\n\nSessions are the app's working-context model. They let you switch cleanly between projects, inventories, and environments without retyping the same flags every time.\n\nCurrent session screen capabilities:\n\n- stacked panels in this order: `Active Workspace`, `Saved Sessions`, `Workspace Notes`\n- activate a session with `Enter`\n- create a session with `n`\n- edit the selected session with `e`\n- delete the selected session with `d`\n- return to the main navigation flow with `Esc`\n\nSession data can include:\n\n- working directory\n- inventory\n- vault password file\n- vault ID\n- extra vars\n- environment variables\n- `ansible.cfg`\n- tags\n- notes\n\n## Jobs And Logs\n\nExecutions run with an active session are recorded as jobs with:\n\n- tool name\n- selected action\n- full command argv\n- session id and session name\n- timestamp\n- exit code\n- duration\n- output log file path\n\nThe Jobs screen provides:\n\n- newest-first job list\n- status badges for success and failure\n- derived target/file column where possible\n- full detail view with command, metadata, and scrollable output\n- deletion of the job entry and its associated log file\n\nOld logs are pruned automatically on startup to keep disk growth bounded.\n\n## Data Storage\n\nPersistent data uses `env-paths('ansi-tui')`, so the base directory varies by OS.\n\nTypical examples:\n\n- macOS: `~/Library/Application Support/ansi-tui`\n- Linux: `~/.local/share/ansi-tui`\n\nLayout:\n\n```text\n/\n├── sessions/ # {uuid}.json per session\n├── active_session # active session id\n├── history/ # {sessionId}.jsonl job history per session\n└── logs/ # {timestamp}-{tool}.log execution output\n```\n\n## Development\n\n```bash\nnpm install\nnpm run dev\nnpm run build # Bundle src/ to dist/\nnpm start # Run built app\n```\n\n\nUseful commands:\n\n```bash\nnpm run lint # ESLint on src/\nnpx tsc --noEmit # Type-check only\nnpm test # Full vitest suite\nnpm run test:core # Core module tests\nnpm run test:tools # Tool tests\nnpm run test:components # Shared component tests\nnpm run test:screens # Screen tests\nnpm run test:hooks # Hook tests\nnpm run test:watch # Vitest watch mode\n```\n\nRun a single test file:\n\n```bash\nnpx vitest run tests/core/jobs.test.ts\nnpx vitest run tests/tools/playbook.test.ts\nnpx vitest run tests/components/Sidebar.test.tsx\nnpx vitest run tests/screens/JobsScreen.test.tsx\nnpx vitest run tests/screens/SessionsScreen.test.tsx\n```\n\n\nCurrent suite expectation:\n\n- `297/297` tests passing\n\n## CI\n\nPull requests run the npm test workflow defined in `.github/workflows/npm-tests.yml`.\n\n- suite-specific test runs for `core`, `tools`, `components`, `screens`, and `hooks`\n- Node.js matrix coverage for `20`, `22`, and `24`\n\n\nMaintainers then run the `Release stable-10` workflow manually and select the branch to release, typically `stable-10`, to publish npm and create the GitHub release.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md","_rev":"1-809bf7dcb1a8fe429760f5bc916b2248"}
![](\"img/banner.png\")
\n