Desktop App Guide

The secretctl desktop app provides a graphical interface for managing your secrets. Built with native performance, it offers the same security as the CLI with an intuitive visual experience.

Overview

The desktop app is designed for:

• Visual users who prefer GUI over command line
• Quick access to view and copy secrets
• Team members who need occasional secret access
• Audit review with visual filtering and export

Features

Secret Management

• Create, view, edit, and delete secrets
• Rich metadata support (notes, tags, URLs)
• Search and filter secrets instantly
• Secure clipboard copy with auto-clear

Security

• Same encryption as CLI (AES-256-GCM + Argon2id)
• Auto-lock after inactivity
• Visual password masking
• Tamper-evident audit logging

Audit Logs

• Visual audit log viewer
• Filter by action, source, date range
• Chain integrity verification
• Export to CSV/JSON

Installation

note

Pre-built binaries are not yet available. Currently, you need to build from source.

Prerequisites

• Go 1.24+
• Node.js 18+ (for frontend build)
• Wails CLI v2
• Platform-specific dependencies (run wails doctor to check)

# Install Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# Verify installation
wails doctor

Build from Source

# Clone the repository
git clone https://github.com/forest6511/secretctl.git
cd secretctl/desktop

# Install frontend dependencies and build
wails build

# The binary will be in desktop/build/bin/

Platform-Specific Notes

macOS: The built app bundle is desktop/build/bin/secretctl-desktop.app

Windows: The executable is desktop/build/bin/secretctl-desktop.exe (requires WebView2)

Linux: The binary is desktop/build/bin/secretctl-desktop (requires WebKit2GTK)

Getting Started

First Launch

1. Launch the app - Open secretctl from your applications
2. Create vault - Set a master password (minimum 8 characters)
3. Start adding secrets - Click "Add Secret" to store your first secret

Returning Users

1. Launch the app
2. Enter master password - Unlock your existing vault
3. Access secrets - Browse, search, or modify your secrets

Interface Overview

Sidebar

The left sidebar displays:

• Secret list - All stored secrets
• Search bar - Filter secrets by name
• Action buttons - Refresh, lock, and navigate

Detail Panel

The right panel shows:

• Secret value - With show/hide toggle
• Metadata - URL, tags, notes
• Timestamps - Created and updated dates
• Actions - Copy, edit, delete

Header Bar

Quick access to:

• Audit Log - View activity history
• Refresh - Reload secret list
• Lock - Secure the vault

Settings

Access settings with Cmd/Ctrl + , or through the Command Palette.

Theme

Choose your preferred appearance:

• Light - Default light theme
• Dark - Dark mode for low-light environments
• System - Automatically match your OS preference

Dark mode reduces eye strain and saves battery on OLED displays.

Language

Select your preferred display language:

• English - Default
• 日本語 (Japanese)

The app will remember your language preference across sessions.

Keyboard Shortcuts

Power users can navigate quickly with shortcuts:

Shortcut	Action
Cmd/Ctrl + K	Command Palette
Cmd/Ctrl + N	New secret
Cmd/Ctrl + F	Focus search
Cmd/Ctrl + ,	Settings
Cmd/Ctrl + C	Copy selected value
Cmd/Ctrl + S	Save changes
Cmd/Ctrl + L	Lock vault
Cmd/Ctrl + /	Show shortcuts
Escape	Cancel editing

See Keyboard Shortcuts for the complete list.

Shared Vault

The desktop app shares the same vault as the CLI:

• Secrets created in CLI appear in the app
• Secrets created in the app are available via CLI
• Both use the same encryption and storage

Vault location: ~/.secretctl/

Comparison with CLI

Feature	Desktop App	CLI
Visual interface	Yes	No
Keyboard shortcuts	Yes	N/A
Batch operations	No	Yes
Scripting/automation	No	Yes
Password generation	No	Yes
Secret injection	No	Yes (run)
Audit log viewer	Yes	Yes

Use the desktop app for visual access and the CLI for automation.

Security Considerations

Auto-Lock

The vault automatically locks after 15 minutes of inactivity. Any mouse or keyboard activity resets the timer.

Clipboard Security

When copying a secret:

• Value is copied to system clipboard
• Auto-clears after 30 seconds
• Toast notification confirms the action

Screen Privacy

• Secret values are hidden by default
• Click the eye icon to reveal temporarily
• Values are masked when switching away

Multi-Field Secrets

The desktop app supports multi-field secrets with pre-defined templates:

Template	Use Case	Fields
Login	Website credentials	username, password
Database	Database connections	host, port, username, password, database
API Key	API credentials	api_key, api_secret
SSH Key	SSH authentication	private_key, passphrase

SSH Keys

The SSH Key template's private_key field uses a textarea input, making it easy to paste multi-line PEM-format keys:

1. Click Add Secret
2. Select SSH Key template
3. Paste your SSH private key into the textarea
4. Optionally add a passphrase
5. Click Save

See Field Names Reference for complete template documentation.

Next Steps

• Keyboard Shortcuts - Master the shortcuts
• Audit Logs - View and export activity logs