Getting Started
Install, first launch, and your first connection
This is the fastest path from opening CLIX for the first time to doing real SSH work. It is written for developers who already understand SSH but are new to CLIX.
What you'll do
- Install the app and allow the first launch
- Create a credential in Keychain first
- Register your first host and connect
What to know before you start
- CLIX runs on macOS 14 or later and is currently distributed as an unsigned app.
- Shell integration and AI CLI hook auto-configuration currently target zsh.
- Before you approve first-launch setup, CLIX does not modify ~/.zshrc, Claude, Codex, or Gemini config files.
- For most people, the easiest way to learn CLIX is to create a Keychain credential first and then attach it to a host.
What you see on the first screen
- Top tab bar: switch between Vaults and open session tabs.
- Vaults sidebar: jump to Hosts, Keychain, Port Forwarding, Snippets, Known Hosts, and Logs.
- Main work area: shows either the selected list view or the live terminal surface.
- Right inspector panel: edit and review the selected host, credential, or forwarding rule.
Recommended order for the first real setup
Install the app and allow the first launch
Move CLIX from the DMG or ZIP into Applications and launch it. If macOS blocks it, try Finder → Control-click → Open first.
Approve it in Privacy & Security if needed
If the app is still blocked, go to System Settings → Privacy & Security and allow CLIX from the security message near the bottom of the page.
Decide whether to enable shell integration
On first launch, CLIX asks whether it should configure ~/.zshrc and AI CLI hooks for you. If you allow it, clix-notify, clix-sessions, clix-handoff, and clix-pick are ready to use right away.
Create a credential in Keychain first
Open Vaults → Keychain and save either an SSH key or a password. It can then be reused across multiple hosts, which makes the rest of the setup easier.
Register your first host and connect
Open Vaults → Hosts, create a host, attach a credential and jump host if needed, and start a session. If the connection fails, check SSH Preflight and Diagnostics before retrying.
Unsigned app note
CLIX is currently distributed without an Apple Developer ID signature. If Control-click → Open is not enough, go to System Settings → Privacy & Security and allow CLIX from the security message near the bottom. Once you allow it, future launches behave like a normal app.
A smooth first run is usually Keychain → Hosts → connect → Port Forwarding if needed → verify AI tool integration. CLIX works best when hosts and credentials are organized before you start opening lots of sessions.
Hosts & Connections
Set up hosts, credentials, and jump hosts first
The CLIX SSH flow starts in Hosts and Keychain. Connection details, credentials, jump hosts, and known_hosts state all live in one place, so it is easy to prepare everything before you connect.
What you'll do
- Keychain credentials
- Jump hosts and routes
- SSH Preflight
Recommended order for the first SSH connection
- Save an SSH key or password first in Vaults → Keychain.
- Create a host in Vaults → Hosts with Alias, Hostname, Port, and Username.
- Attach a credential and jump host if your environment needs them.
- Review the route and forwarding setup before opening the session.
- If it fails, check SSH Preflight first and then use Diagnostics to inspect the actual runtime logs.
Host registration
The host editor manages alias, address, port, username, collection, and notes. Favorites and recent connections also surface here, so large server inventories stay manageable.
Keychain credentials
Credentials are reusable SSH assets such as private keys and passwords. Secrets are stored through macOS Keychain and CLIX secure storage, then linked to multiple hosts when needed.
Jump hosts and routes
If you connect through a bastion, configure the route first. Once you attach a jump host, CLIX shows the next connection path and related route details together.
Known Hosts management
If a host key changes and a connection is blocked, open Vaults → Known Hosts. Reset Stored Host Key removes the saved trust entry so the next connection can re-establish trust cleanly.
SSH Preflight
Preflight checks destination details, credentials, routes, forwarding rules, and runtime readiness before the next SSH session. It is the fastest way to see what is missing before you blindly retry.
Collections, tags, and search
The Hosts list can be navigated by alias, address, tags, notes, favorites, and recent usage. Grouping production and personal servers into collections helps reduce mistakes.
Port Forwarding
Turn development environment setup into saved forwarding rules
CLIX is not just an SSH launcher. It also keeps the port-forwarding part of remote development in the same workspace, which is especially useful when you repeatedly open local web previews, databases, or internal tools.
What you'll do
- Creating rules
- Auto-start on connect
- Status and conflict handling
When it helps most
Use it when you want to open a remote app in your local browser, connect to an internal database from a desktop tool, or create a SOCKS proxy for a private network. CLIX stores these rules alongside the host that needs them.
Supported forwarding types
- Local: bring a remote port to localhost on your Mac.
- Remote: expose a local port from your Mac on the remote side.
- Dynamic (SOCKS): create a SOCKS5 proxy for tools and browsers.
Creating rules
Add a rule from Vaults → Port Forwarding or from the host editor. Give it a name, choose the forwarding type, and enter the relevant local and remote addresses and ports.
Auto-start on connect
If a rule should always come up with the SSH session, enable auto-start. It is ideal for repeated web previews or database tunnels you use every day.
Status and conflict handling
Rules surface states such as Connecting, Active, and Failed. CLIX also helps you catch port conflicts and then trace failures through logs and diagnostics.
Terminal Workflow
Organize tabs and terminals around real work
The core CLIX experience is not just opening SSH. It is grouping local terminals and remote sessions into a workflow you can rename, reorder, recover, and reuse.
What you'll do
- Opening new sessions
- Rename and reorder
- Workspace recovery
Basic structure
The top tab bar represents work groups, the left Terminals list represents terminals within the current tab, and the right side is the live terminal surface. A single tab can hold multiple related terminals.
Opening new sessions
Use the + button in the tab bar or inside a session to open a new local terminal or attach a remote host session. You can keep local and remote terminals inside the same work group when that makes sense.
Rename and reorder
Tabs and terminals both support rename, duplicate, close, close others, and drag reordering. During inline rename, Enter or Tab saves the change and Escape cancels it.
Grouping by drag and drop
You can drag one session tab into another tab's terminal list to combine related work. You can also promote a terminal back out into its own tab when you want to separate it again.
Working with snippets
Reusable commands can be stored in Vaults → Snippets and executed directly in the current session. This works well for health checks, deploy prep commands, and repeated SSH utilities.
Workspace recovery
When CLIX relaunches, it restores the tabs, terminals, connection summaries, and last known working directories from the previous session. Recovery also helps after system sleep or reconnect flows.
AI Tool Usage
Attach AI CLI workflows to your CLIX terminals
CLIX does not run AI services itself. It makes Claude Code, Codex, and Gemini CLI easier to use inside your SSH and terminal workflow through notifications, session lists, handoff, and interactive resume helpers.
What you'll do
- What gets auto-configured
- clix-notify — completion notifications
- clix-pick — interactive session resume
What gets auto-configured
If you approve setup on first launch, CLIX updates ~/.zshrc and the Claude, Codex, and Gemini config files once. Existing hooks are not duplicated, and you can turn future auto-configuration off later in Settings.
Important: zsh-first
Shell integration and working-directory tracking currently rely on zsh. Even if AI CLI hooks are present elsewhere, the chpwd-driven directory updates and notification flow are most reliable in zsh.
clix-notify — completion notifications
Registers an in-app notification in CLIX when an AI task finishes. If you are not looking at that session, CLIX can also surface the event through the session notification panel and macOS banners.
clix-sessions — list open sessions
Prints the currently open tabs and their active working directories. It is the simplest reference when you want to target a specific tab directly.
clix-handoff — resume from a specific tab
Moves into the selected tab's working directory and launches the AI CLI there. It is the most straightforward way to continue work in the exact context of another open CLIX session.
clix-pick — interactive session resume
The main resume helper. It shows currently open CLIX sessions with recent Claude, Codex, or Gemini activity so you can interactively pick the one you want to continue.
Browser Automation
Control the browser from the terminal
clix-browser lets AI agents open, interact with, and verify browser state using terminal commands — no separate automation tool needed.
What you'll do
- open / navigate — open and move
- snapshot — interactive element list
- click / fill / press — interact with elements
- screenshot / evaluate — verify results
When to use it
Use clix-browser when an AI agent needs to verify web UI state or run automation flows. It controls the CLIX built-in browser directly via commands.
Core rule: open a tab only once
Use open to create a tab the first time, then navigate for all subsequent URL changes. Opening new tabs repeatedly splits context.
open / navigate — open and move
open <url> creates a new tab and resets refs. navigate <url> changes the URL in the current tab. Use list to see open tabs.
snapshot — interactive element list
snapshot prints clickable elements with their ref numbers. You can also target elements by CSS selector (e.g., click "#submit") instead of ref number. Ref numbers reset on navigation, so run snapshot again before interacting.
click / fill / press — interact with elements
Use the ref number from snapshot or a CSS selector with click, fill, or press. fill <ref> <text> sets input text; press sends keys like Enter, Escape, or Tab.
screenshot / evaluate — verify results
screenshot returns the current view as PNG base64. evaluate <script> runs JavaScript and returns the result. Both are useful for checking state.
list / activate / close — tab management
Use list to see open tabs, activate <tab-id> to switch, and close <tab-id> to close a tab.
wait — wait for load or condition
wait --load-state blocks until the page fully loads. wait --selector <css> waits until the element appears in the DOM; wait --text <text> waits until the text appears on the page. Use --timeout-ms to set a custom timeout.
console — capture browser logs
The console command returns browser console.log and console.error output. The last 200 messages are kept in a ring buffer, making it useful for debugging page scripts.
get / is — query page state
get title, get url, and get text <selector> return the page title, URL, or element text. is visible <selector> and is enabled <selector> check element state without interacting.
Advanced targeting — CSS selectors, --snapshot-after, --tab
CSS selectors let you target elements without a ref number (e.g., click "#login-btn"). Add --snapshot-after to navigate or click to automatically return a snapshot after the action. Use --tab <tab-id> to explicitly target a specific tab.
Alerts, Recovery & Backup
Don't miss long-running work, trace issues, and preserve your setup
CLIX is designed to track working state, not just open connections. Session alerts, reconnect flows, Diagnostics, and Backup & Restore all become more useful once you see them as parts of the same operating workflow.
What you'll do
- Session alerts
- SSH Diagnostics
- Exporting a backup
Session alerts
Use the notification button in the top-right corner to review completed or attention-worthy session events. Opening an unread item jumps straight back to the related tab and terminal.
Reconnect and session recovery
When a session drops or the system wakes from sleep, CLIX can guide the reconnect flow. Credential repairs and known_hosts recovery can be handled from the same general path instead of restarting from scratch.
SSH Diagnostics
Diagnostics shows the managed known_hosts path, the diagnostics directory, the SSH wrapper path, and the latest stderr output for each session. It is the most direct place to inspect real SSH runtime failures.
Exporting a backup
Use Backup & Restore to save hosts, routes, snippets, and credentials into a backup file. You can choose whether secure secrets are included, which helps separate personal backups from safer team sharing.
Importing a restore
Use the same window to restore a previous environment on another Mac or recover your own setup. Restoring can overwrite both the current CLIX configuration and secure stored values, so confirm the scope before proceeding.
Best order when something breaks
When a connection fails, Preflight → Diagnostics → Known Hosts → credential review is usually faster than repeatedly retrying. If you missed a long-running task, start with the notification panel to jump back to the right session.
Settings & Shortcuts
Frequently changed settings and worth-remembering shortcuts
CLIX settings are grouped into Appearance, Terminal, and Launch. If you also learn the few keyboard-driven actions that matter in daily use, the app becomes much smoother to navigate.
What you'll do
- Appearance
- Terminal
- Shortcuts and input rules to remember
Appearance
Adjust the app language, app appearance, and terminal theme. The guide and the app follow the same language choice, which is helpful when reviewing translations or sharing flows with teammates.
Terminal
Change the font family, font size, cursor style, and scrollback lines. If you spend a lot of time reading logs, font size and scrollback are usually the first settings worth tuning.
Launch
Manage the local shell launch mode and shell integration auto-configuration. Compatible behaves more like a login shell, while Fast starts quicker but may skip some login-only shell setup.
Shell integration controls
If auto-configuration is off, CLIX will not modify ~/.zshrc or AI CLI config files for you. If you already approved setup once, this is where you control future behavior.
Shortcuts and input rules to remember
- ⌘W: closes the current active session surface. If there is only one terminal left in the tab, it closes the tab; otherwise it closes the active terminal within that tab.
- During tab or terminal rename, Enter / Tab saves the new name.
- During tab or terminal rename, Escape cancels the rename.
- In modal dialogs, Enter triggers the default action and Escape cancels.
Recommended settings for new users
For the first few days, it is usually enough to adjust App Language, terminal font size, Local Shell Launch, and shell integration auto-configuration. Leave the rest at defaults until the forwarding and AI CLI workflow feels familiar.