trm alias

Author: terion-labs

ansible/roles/base/tasks/main.yml

@@ -46,6 +46,35 @@
     mode: "0755"
     remote_src: true
 
+- name: Inspect existing terrariumctl shorthand alias
+  ansible.builtin.stat:
+    path: /usr/local/bin/trm
+    follow: false
+  register: terrarium_trm_alias
+
+- name: Install terrariumctl shorthand alias
+  ansible.builtin.file:
+    src: /usr/local/bin/terrariumctl
+    dest: /usr/local/bin/trm
+    state: link
+    force: true
+  when: >-
+    not terrarium_trm_alias.stat.exists
+    or (
+      terrarium_trm_alias.stat.islnk | default(false)
+      and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
+    )
+
+- name: Warn when terrariumctl shorthand alias is unavailable
+  ansible.builtin.debug:
+    msg: /usr/local/bin/trm already exists and is not managed by Terrarium; leaving it untouched.
+  when: >-
+    terrarium_trm_alias.stat.exists
+    and not (
+      terrarium_trm_alias.stat.islnk | default(false)
+      and terrarium_trm_alias.stat.lnk_source == "/usr/local/bin/terrariumctl"
+    )
+
 - name: Ensure root has a local password for Cockpit
   ansible.builtin.user:
     name: root

docs/reference/terrariumctl.md

@@ -1,6 +1,6 @@
 # terrariumctl
 
-`terrariumctl` is the main Terrarium control surface. It handles install, status, reconfiguration, proxy sync, IDP sync, backup export, and restore.
+`terrariumctl` is the main Terrarium control surface. It handles install, status, reconfiguration, proxy sync, IDP sync, backup export, and restore. Installed hosts also provide `trm` as a shorthand alias for the same command.
 
 ## Top-Level Commands
 

tests/ansible-base.test.ts

@@ -36,6 +36,19 @@ describe("config store reconciliation", () => {
   });
 });
 
+describe("terrariumctl install alias", () => {
+  test("installs trm as a shorthand symlink to the installed CLI", () => {
+    const tasks = readFileSync(join(repoRoot, "ansible/roles/base/tasks/main.yml"), "utf8");
+
+    expect(tasks).toContain("Inspect existing terrariumctl shorthand alias");
+    expect(tasks).toContain("Install terrariumctl shorthand alias");
+    expect(tasks).toContain("src: /usr/local/bin/terrariumctl");
+    expect(tasks).toContain("dest: /usr/local/bin/trm");
+    expect(tasks).toContain("state: link");
+    expect(tasks).toContain("leaving it untouched");
+  });
+});
+
 describe("terrariumctl mount defaults", () => {
   test("disable client-side CIFS permission checks for single-credential managed mounts", () => {
     const mount = readFileSync(join(repoRoot, "scripts/ctl/mount.ts"), "utf8");

tests/integration/scenarios/common.ts

@@ -243,6 +243,7 @@ export async function installTerrarium(context: IntegrationContext, host: Manage
   ].join(" && ");
   await ssh.execDetached(installCommand, remoteScriptPath, remoteStatusPath, remoteLogPath);
   await waitForDetachedCommand(ssh, remoteStatusPath, remoteLogPath, 45 * 60 * 1000);
+  await ssh.exec("test -L /usr/local/bin/trm && /usr/local/bin/trm status >/dev/null");
 }
 
 /** Returns the local ZITADEL bootstrap credentials from an installed Terrarium host. */