Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formal.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Formal Desktop App simplifies connecting to protected resources by automating authentication and connection management. It also includes a powerful CLI.

​
Access

Contact Formal support or your workspace administrator for approved Desktop App distribution and deployment guidance.

​
Setup

1

Launch the App

Start Formal - you’ll see the logo in your system tray
2

Install CLI (macOS)

Click the tray icon → Preferences → Install in PATH Or manually: bash sudo ln -s /Applications/Formal.app/Contents/MacOS/formal /usr/local/bin/formal
3

Log In

bash formal auth login
4

Verify

bash formal ls You should see all available resources

​
Connecting to Resources

​
Avoiding Credentials

After you log in, confirm your session with: 
formal auth whoami
When you run formal connect for a , the Desktop App injects Formal credentials for you. You do not pass Formal usernames or passwords to the client.
  • SSH and Kubernetes: Your ~/.ssh/config and ~/.kube/config are updated so tools use the right paths and identity.
  • Other technologies: A localhost listener is started. Point your client at that address and port without supplying Formal credentials.

​
Transparent Proxy

Transparent proxy is supported on macOS only.
The Desktop App can route traffic for a resource hostname through the Formal . You use the resource’s real hostname. You do not apply Formal credentials on the client. One-time setup
  1. Run:
formal transparent-proxy install
  1. Approve any system prompts so the Formal Desktop App network extension can run.
  2. Start the transparent proxy: 
formal transparent-proxy enable
Connect 
formal connect <resource-name>
Replace <resource-name> with the name from formal ls. Traffic to that resource’s hostname then goes through the Connector transparently.

​
CLI Reference

​
Optional Update Checks

Desktop App update checks are disabled by default. To enable update polling and the tray update icon, add this to ~/.formal/config.toml: 
check_for_updates = true

​
Authentication

# Log in
formal auth login

# Get your credentials (for direct connections)
formal auth credentials

​
List Resources

formal ls
Interactive TUI with:
  • ↑/k - Move up
  • ↓/j - Move down
  • enter - Connect to resource
  • / - Filter resources
  • q - Quit
  • ? - Show help

​
Connect to Resources

​
Databases (PostgreSQL, MySQL, MongoDB)

# Connect to a database
formal connect production-postgres

# Output:
# Connected to production-postgres on localhost:6432
Then connect with your database client: 
# PostgreSQL
psql -h localhost -p 6432 -d postgres

# MySQL
mysql -h localhost -P 6432 -d mysql

# MongoDB
mongosh "mongodb://localhost:27017/mydb"
Formal automatically injects your credentials - no username/password needed! Note that the database name is required for the connection to be successful. You can also use the --launch argument to launch the appropriate CLI program after connecting (for example psql or ssh), e.g. 
# uses the database name from the config file in ~/.formal/config.toml
formal connect --launch production-postgres

​
Specify Native User

If you need to specify a different native user than the default one assign to your user, you can specify using the convention: formal@[the_name_of_the_native_user]. 
# PostgreSQL with specific native user
psql -h localhost -p 6432 -U formal@readonly

​
SSH

# List resources
formal ls
# Select an SSH resource and press enter
This updates your ~/.ssh/config automatically.

​
Kubernetes

# Configure kubectl
formal ls
# Select a Kubernetes resource and press enter
This updates your ~/.kube/config to route through the Connector.

​
Disconnect

# Disconnect from a resource
formal disconnect production-postgres

​
Policy Evaluation

Test policies locally: 
formal policy evaluate \
  --inputs '{"user_id":"abc123"}' \
  -r session

​
Decrypt Data

Decrypt Formal-encrypted data: 
formal decrypt --ciphertext "formalencrypt:second:third:fourth:fifth"

​
S3 Operations

The Formal s3 command automatically routes traffic to the right Connector so your users don’t have to worry about formatting the right parameters for S3. Interact with S3 through Formal: 
formal s3 ls s3://my-bucket
See AWS CLI S3 commands for more operations.

​
Device Trust

The Desktop App reports device information for policy enforcement:
  • Hardware model and serial number
  • OS version and security settings
  • System Integrity Protection status
  • Secure boot status
See MDM Integration for device-based policies.

​
Headless Mode

The Formal Desktop app supports being launched in headless mode. This can be useful in server environments without a GUI or keyring support. To start the agent in headless mode, you can use the following command: 
formal agent --headless
Now in a separate terminal, you can run the Formal CLI as normal to connect to resources and get credentials: 
formal auth login
formal auth credentials
formal ls
formal connect [resource-name]
In headless mode, Formal credentials are only stored in the agent’s memory. This means that you’ll need to reauthenticate when restarting the agent (e.g., when the machine itself reboots).

​
Using an API Key

The Formal Desktop app supports using an API key to authenticate to the Control Plane. First, you will need to create an API key on the Formal Console. Create one under API Keys in the console. To start the agent with an API key, you can use the following command: 
FORMAL_API_KEY=<api-key> formal agent
You can also run the agent in headless mode with an API key: 
FORMAL_API_KEY=<api-key> formal agent --headless

​
MDM Deployment

Deploy the Desktop App organization-wide via your MDM with an approved package from Formal support:
  1. Request the approved deployment package from Formal support.
  2. Add it as a custom app in your MDM (Jamf, Intune, etc.).
  3. Push it to all user devices.
Need help deploying via MDM? Contact Formal support for assistance.

​
Troubleshooting

Error: WARNING: CLI cannot connect to the Formal app. Please make sure the Formal app is running.Solution:
  1. Check that Formal is visible in system tray
  2. Restart the Formal app
  3. On Linux: systemctl start --user formal
Error: bash: formal: command not foundSolution:
  1. Reinstall CLI: Click tray icon → Preferences → Install in PATH
  2. Or create symlink manually (see Setup section)
  3. Or add alias to .bashrc/.zshrc
Solution:
  1. Check resource exists: formal ls
  2. Ensure Connector is running
  3. Check network connectivity

​
Best Practices

The Desktop App must be running for CLI commands to work. Enable “Launch at startup” in preferences.
When connecting via formal connect, use tab completion to find resources quickly.
formal ls provides an interactive way to explore and connect to resources without memorizing names.
Always disconnect from resources when finished to free up local ports.