Skip to content

feat: termora-cli — a CLI for AI agents to reuse saved SSH hosts#1564

Open
ruanun wants to merge 1 commit into
TermoraDev:2.xfrom
ruanun:feat/termora-cli-exec
Open

feat: termora-cli — a CLI for AI agents to reuse saved SSH hosts#1564
ruanun wants to merge 1 commit into
TermoraDev:2.xfrom
ruanun:feat/termora-cli-exec

Conversation

@ruanun

@ruanun ruanun commented Jul 1, 2026

Copy link
Copy Markdown

Summary

Adds termora-cli, a command-line entry (shipped via jpackage --add-launcher) that lets external AI agents — Claude Code, Codex, etc. — reuse the SSH hosts already saved in Termora to run one-off commands and transfer files, without ever exposing credentials. Paired with a bundled SKILL.md, an agent can drive it directly.

Features

  • Commands: assets list / exec / upload / download; JSON output when piped, human-readable in a TTY
  • exec opens a temporary SSH connection (reuses core SshClients, incl. jump hosts) and returns clean stdout/stderr/exit code
  • Defense-in-depth, opt-in (default off): master switch + host whitelist (empty by default) + dangerous-command guard + audit log
  • Settings → "Command Line": enable switch, tree-grouped host whitelist (non-SSH hosts greyed out), copy / install the Skill to Claude & Codex, add termora-cli to PATH
  • Bundled SKILL.md (a format shared by Claude Code and Codex)

Design

  • Standalone launcher talking to core directly (the DB is self-unlocking, so no running GUI is required); no MCP/HTTP layer — kept minimal.
  • Built-in, not an external plugin: the CLI depends deeply on core SSH/credential handling and the launcher is a build artifact, so it can't be a loadable plugin; optionality is expressed via the default-off master switch.

Changes

  • New app.termora.cli.** (CLI core) and app.termora.plugin.internal.cli.** (settings UI)
  • Core: register an internal plugin in PluginManager; widen ApplicationInitializr.setupNativeLibraries to internal for CLI reuse; build.gradle.kts adds --add-launcher + --enable-native-access and tightens the pty4j native-extraction glob
  • i18n for all 6 languages; adds SKILL.md

Testing

  • 33 unit tests + 8 integration tests (Testcontainers real sshd)
  • Verified end-to-end on Windows: full jpackage build, real-host exec/upload/download (incl. a jump host), master-switch default-off, native warnings suppressed

Notes for reviewers

  • The CLI reuses SshClients from the *.internal.ssh package (public API, "internal" package) — mirrors the existing headless SFTP path; happy to promote it to a dedicated public API if preferred.
  • Cross-platform packaging (macOS/Linux add-launcher, PathInstaller symlink, pty4j extraction) is code-reviewed and reasoned correct but only build-tested on Windows — CI on the other platforms would be the final confirmation.

A termora-cli command (jpackage add-launcher, ships with the app) lets external AI agents such as Claude Code / Codex reuse the SSH hosts saved in Termora to run commands and transfer files, without ever exposing credentials. Commands: assets list / exec / upload / download. Defense-in-depth, opt-in (default off): master switch + host whitelist + dangerous-command guard + audit log. Settings page "Command Line": enable switch, tree-grouped host whitelist, copy/install Skill to Claude/Codex, add to PATH. Ships SKILL.md; i18n for all 6 languages.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant