### Running Localias Proxy Server in Foreground (Initial Setup)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet illustrates starting the Localias proxy server in the foreground for the first time using `localias run`. It highlights the initial authentication prompts required for /etc/hosts modifications and local root certificate generation/installation, followed by server logs indicating certificate acquisition.

```console
$ localias run
# some prompts to authenticate as root
# ... lots of server logs like this:
2023/05/02 23:12:58.218 INFO	tls.obtain	acquiring lock	{"identifier": "frontend.test"}
2023/05/02 23:12:58.229 INFO	tls.obtain	lock acquired	{"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO	tls.obtain	obtaining certificate	{"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO	tls.obtain	certificate obtained successfully	{"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO	tls.obtain	releasing lock	{"identifier": "frontend.test"}
# process is now waiting for requests
```

--------------------------------

### Installing Localias via Go

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command installs the `localias` executable from its Go module source to your Go binary path (e.g., `$GOPATH/bin`), making it permanently available in your system's PATH.

```go
go install github.com/peterldowns/localias/cmd/localias@latest
```

--------------------------------

### Verifying localias Daemon Status

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet demonstrates attempting to start the localias daemon and then checking its status. It shows that the daemon is not running, which often points to underlying port binding issues preventing it from initializing correctly.

```console
$ localias start
$ localias status
daemon is not running
```

--------------------------------

### Installing Localias with Homebrew

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command installs Localias on macOS and Linux systems using Homebrew, a popular package manager. It adds the `peterldowns/tap` tap and then installs the `localias` package.

```bash
brew install peterldowns/tap/localias
```

--------------------------------

### Installing Localias via Nix Flakes

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command installs the `localias` tool into the user's Nix profile, making it persistently available in the system. The `--refresh` flag ensures the latest flake is fetched.

```nix
nix profile install --refresh github:peterldowns/localias
```

--------------------------------

### Running Localias via Go (Temporary)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command executes the `localias` tool directly from its Go module source, allowing for temporary usage without a full installation. It fetches the latest version and displays the help message.

```go
go run github.com/peterldowns/localias/cmd/localias@latest --help
```

--------------------------------

### Displaying Localias CLI Help and Commands (Console)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This console output shows the main help message for the `localias` CLI, detailing its usage, examples for common operations like setting/removing aliases and managing the daemon, and a list of all available subcommands and global flags. It serves as a quick reference for `localias` functionality.

```Console
$ localias
securely manage local aliases for development servers

Usage:
  localias [flags]
  localias [command]

Examples:
  # Add an alias forwarding https://secure.test to http://127.0.0.1:9000
  localias set secure.test 9000
  # Update an existing alias to forward to a different port
  localias set secure.test 9001
  # Remove an alias
  localias rm secure.test
  # List all aliases
  localias list
  # Clear all aliases
  localias clear
  
  # Start the proxy server as a daemon process
  localias start
  # Show the status of the daemon process
  localias status
  # Apply the latest configuration to the proxy server in the daemon process
  localias reload
  # Stop the daemon process
  localias stop
  # Run the proxy server in the foreground
  localias run

Available Commands:
  clear       clear all aliases
  help        Help about any command
  list        list all aliases
  reload      apply the latest configuration to the proxy server in the daemon process
  rm          remove an alias
  run         run the proxy server in the foreground
  set         add or edit an alias
  start       start the proxy server as a daemon process
  status      show the status of the daemon process
  stop        stop the daemon process
  version     show the version of this binary

Flags:
  -c, --configfile string   path to the configuration file to edit
  -h, --help                help for localias
  -v, --version             version for localias

Use "localias [command] --help" for more information about a command.
```

--------------------------------

### Diagnosing localias Startup Failure

Source: https://github.com/peterldowns/localias/blob/main/README.md

This console output shows the error message when `localias run` fails to start, indicating a port conflict on 443/80 or another localias instance. It lists common causes for the failure, such as other proxy servers or a bug in localias.

```console
$ localias run
error: localias could not start successfully. Most likely there is another instance of
localias or some other kind of proxy or server listening to ports 443/80, which
is preventing another instance from starting. Common causes:

- You have another instance of localias running in a different terminal
- You have a proxy server like Caddy, Nginx, or Apache running
- There is a bug in localias

Please see the https://github.com/peterldowns/localias README for some
diagnostics and ideas for how to debug this.
```

--------------------------------

### Example Localias Configuration File

Source: https://github.com/peterldowns/localias/blob/main/README.md

This YAML snippet illustrates the structure of a Localias configuration file, mapping alias domain names to their respective local ports. It demonstrates various alias types, including bare TLDs, implicitly secure, explicitly secure (HTTPS), and explicitly insecure (HTTP) aliases.

```yaml
bareTLD: 9003 # serves over https and http
implicitly_secure.test: 9002 # serves over https and http
https://explicit_secure.test: 9000 # serves over https and http
http://explicit_insecure.test: 9001 # serves over http only
```

--------------------------------

### Localias Daemon Not Running Due to Permissions (Linux)

Source: https://github.com/peterldowns/localias/blob/main/README.md

These commands demonstrate that the Localias daemon fails to start and run properly on Linux when port binding permissions are insufficient. After attempting to start, `localias status` will report `daemon is not running`, indicating a failure to initialize due to permission issues.

```bash
localias start
localias status
```

--------------------------------

### Installing Localias Root Certificate on Windows

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command installs the Localias root signing certificate into the Windows machine's certificate store. This is necessary when running Localias inside WSL and using a Windows browser to avoid certificate warnings for secure aliases. Executing this command will prompt for administrator authorization.

```bash
localias debug cert --install
```

--------------------------------

### Managing Localias Proxy Server as a Daemon

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet provides a set of commands for interacting with the Localias proxy server when it's running as a background daemon. It includes commands to start, check the status, reload the configuration, and stop the daemon process.

```shell
# Start the proxy server as a daemon process
localias start
# Show the status of the daemon process
localias status
# Apply the latest configuration to the proxy server in the daemon process
localias reload
# Stop the daemon process
localias stop
```

--------------------------------

### Adding Local Aliases for .local Domains

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet demonstrates how to create local aliases using the `localias add` command. It shows examples for both a secure alias (`frontend.local`) and an insecure alias (`http://insecure.local`), mapping them to port 8080. These `.local` domains are broadcast via mDNS for network-wide access, making development servers accessible from other devices on the network.

```console
$ localias add frontend.local 8080
[added] frontend.local -> 8080
$ localias add http://insecure.local 8080
[added] http://insecure.local 8080
```

--------------------------------

### Finding Processes Listening on Ports 80/443 with lsof

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command utilizes `lsof -Pn | grep -E '\*:443|\*:80'` to identify processes listening on ports 80 or 443. It's crucial for diagnosing port conflicts that prevent localias from starting, showing which process is occupying the necessary ports.

```console
$  lsof -Pn | grep -E '\*:443|\*:80'
localias  39020   pd    9u     IPv6 0xb3abbd50442d943f       0t0                 TCP *:443 (LISTEN)
localias  39020   pd   11u     IPv6 0xb3abbd4b78f6ba3f       0t0                 UDP *:443
localias  39020   pd   12u     IPv6 0xb3abbd50442da23f       0t0                 TCP *:80 (LISTEN)
```

--------------------------------

### Converting Localias Certificate Path to Windows Format (WSL)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command converts the Linux path of the Localias root certificate into a Windows-compatible UNC path, for example: `\\wsl$\Ubuntu-20.04\home\pd\.local\state\localias\caddy\pki\authorities\local\root.crt`. This is essential for accessing the certificate from Windows applications like Firefox when running Localias within WSL.

```bash
wslpath -w $(localias debug cert)
```

--------------------------------

### Finding Localias Root Certificate Path (MacOS/Linux)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command prints the file path to the Localias root certificate on MacOS or Linux, for example: `/Users/pd/Library/Application Support/localias/caddy/pki/authorities/local/root.crt`. This path is necessary for manually importing the certificate into Firefox or other applications that do not automatically trust the system store.

```bash
localias debug cert
```

--------------------------------

### Localias Port Binding Permission Denied Error (Linux)

Source: https://github.com/peterldowns/localias/blob/main/README.md

Executing `localias run` on Linux without proper permissions can result in a 'permission denied' error when attempting to bind to privileged ports like 443. The full error message typically includes `error: loading new config: http app module: start: listening on :443: listen tcp :443: bind: permission denied`.

```bash
localias run
```

--------------------------------

### Listing Existing Localias Aliases

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet shows how to verify that an alias has been added correctly by listing all currently configured aliases using the `localias list` command, displaying their domain-to-port mappings.

```console
$ localias list
frontend.test -> 3000
```

--------------------------------

### Listing All Localias Aliases

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command displays a list of all currently configured aliases and their corresponding local ports from the Localias configuration file.

```shell
localias list
```

--------------------------------

### Setting a New Alias with Localias

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet demonstrates how to create a new alias using the `localias set` command. It maps a custom domain, `frontend.test`, to a local port, `3000`, allowing access to a local development server.

```console
$ localias set frontend.test 3000
[added] frontend.test -> 3000
```

--------------------------------

### Running Localias via Nix Flakes (Temporary)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command executes the `localias` tool using Nix flakes, providing a temporary, reproducible environment to run the application and display its help message.

```nix
nix run github:peterldowns/localias -- --help
```

--------------------------------

### Displaying Localias Configuration File Path

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command prints the absolute path to the Localias configuration file currently being used by the application, based on its search order.

```bash
localias debug config
```

--------------------------------

### Restarting Localias Proxy Server in Foreground

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet demonstrates restarting the Localias proxy server in the foreground after it has been run at least once. It shows that subsequent runs typically do not prompt for sudo authentication, as the necessary system modifications have already been performed.

```console
^C
$ localias run
# ... lots of server logs
# ... but no sudo prompts!
```

--------------------------------

### Printing Localias Configuration File Contents

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command outputs the full contents of the active Localias configuration file to the console, useful for inspecting current alias definitions.

```bash
localias debug config --print
```

--------------------------------

### Granting Port Binding Permissions to Localias (Linux)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This `setcap` command grants the `CAP_NET_BIND_SERVICE` capability to the `localias` executable. This allows the Localias binary to bind to privileged ports (like 80 and 443) on Linux without requiring root privileges for every execution, resolving 'permission denied' errors.

```bash
sudo setcap CAP_NET_BIND_SERVICE=+eip $(which localias)
```

--------------------------------

### Identifying Running localias Instances with ps

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command uses `ps aux | grep -i localias` to list all running processes that contain 'localias' in their name. It helps determine if another instance of localias is already active and potentially causing port conflicts on ports 80/443.

```console
$ ps aux | grep -i localias
pd               39020   0.0  0.1 409289408  38736 s003  S+    1:42PM   0:00.09 localias run
pd               39198   0.0  0.0 407965536    624 s005  R+    1:47PM   0:00.00 grep -i localias
```

--------------------------------

### Adding or Updating a Localias Alias

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command adds a new alias or updates an existing one in the Localias configuration file. `<alias>` specifies the domain name (e.g., `server.test`) and `<port>` is the local port it should proxy to (e.g., `3000`).

```shell
localias set <alias> <port>
```

--------------------------------

### Reloading Localias Daemon After Configuration Changes

Source: https://github.com/peterldowns/localias/blob/main/README.md

This snippet illustrates the process of updating an alias and then explicitly reloading the Localias daemon to apply the new configuration. It highlights that changes made to aliases require a `localias reload` command when the server is running as a background daemon.

```shell
# Start with frontend.test -> 3000
localias set frontend.test 3000
localias start
# Update frontend.test -> 4004. 
localias set frontend.test 4004
# The daemon will still be running with frontend.test -> 3000, so
```

--------------------------------

### Enabling System Root Trust in Firefox (MacOS/Linux)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This configuration setting allows Firefox on MacOS and Linux to trust certificates from the system's root certificate store, which includes certificates generated by Localias. This avoids security warnings when accessing secure local aliases.

```Firefox Configuration
security.enterprise_roots.enabled = true
```

--------------------------------

### Reloading Localias Configuration (Shell)

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command reloads the `localias` proxy server to apply the latest configuration changes. It is typically used after modifying aliases or other settings to ensure the changes take effect without restarting the daemon.

```Shell
localias reload
```

--------------------------------

### Clearing All Localias Aliases

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command removes all defined aliases from the Localias configuration file, effectively resetting the alias list.

```shell
localias clear
```

--------------------------------

### Removing a Localias Alias

Source: https://github.com/peterldowns/localias/blob/main/README.md

This command deletes a specific alias from the Localias configuration file. `<alias>` should be the exact domain name of the alias to be removed.

```shell
localias remove <alias>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.