Metadata-Version: 2.4
Name: ssh-profile
Version: 0.2.0
Summary: Network-aware SSH config profile selector
Author-email: Scott Karlin <pypi@karlin-online.com>
Maintainer-email: Scott Karlin <pypi@karlin-online.com>
License: MIT
Project-URL: homepage, https://gitlab.com/sck/ssh-profile
Project-URL: bugs, https://gitlab.com/sck/ssh-profile/-/issues
Project-URL: changelog, https://gitlab.com/sck/ssh-profile/-/blob/main/HISTORY.md
Project-URL: documentation, https://sck.gitlab.io/ssh-profile/
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: attrs>=26.1.0
Requires-Dist: argparse-utilities>=0.0.2
Dynamic: license-file

# SSH Profile

![PyPI version](https://img.shields.io/pypi/v/ssh-profile.svg)

Network-aware SSH config profile selector.

`ssh-profile` answers one question -- *which profile applies on the network
this machine is on right now?* -- so your `~/.ssh/config` can pick the SSH
options that fit.  One shared `~/.ssh/config` + `ssh-profile.toml` pair then
works across all your machines and networks, instead of per-machine configs
that drift.

## Features

* **Network-aware profile selection** -- detect which profile applies on the
  current network and use it as an `ssh_config` `Match exec` predicate.
* **Four detection tiers**, evaluated as a first-match-wins cascade:
  `hostname`, `cidr` (wired IPv4), `gateway_mac`, and `ssid`.
* **Safe by design** -- predicate mode is silent on stdout; lenient runtime
  loading fails toward the conservative `unknown` profile; a broken `ssh-profile`
  fails the connection loudly rather than misconnecting.
* **Validation built in** -- `--check-config` checks the profile data file and
  your `~/.ssh/config` references; `--check-tools` checks for the existence of
  the `ip`/`ping`/`iw` tools.
* **Fast** -- a short-TTL cache speeds up the burst of `ssh-profile`
  invocations generated by an ssh connection; the initial network
  detection is shared across the burst.
* **One shared config** -- a common `~/.ssh/config` + `ssh-profile.toml` pair
  can be used (sync'd) across machines avoiding per-machine drift.

## Installation

`ssh-profile` is a CLI tool hosted on PyPI, so a common installation
method is to use [`pipx`](https://pipx.pypa.io/) as follows:

```sh
pipx install ssh-profile
```

Other install methods (plain `pip`, `uv`, from source) are covered in the
[Installation guide](https://sck.gitlab.io/ssh-profile/installation/).

## Quick start

`ssh-profile` reads its profiles and detection rules from
`~/.ssh/ssh-profile.toml`.
Here is a simple example with two profiles -- one matched by Wi-Fi SSID, the
other by a wired IPv4 range:

```toml
[profiles]
home       = "Trusted home LAN"
work-wired = "Office, wired"

[[tiers]]
kind  = "ssid"
rules = [{ ssid = "HomeNet", profile = "home" }]

[[tiers]]
kind  = "cidr"
rules = [{ network = "203.0.113.0/24", profile = "work-wired" }]
```

With that file in place, `ssh-profile` prints the profile that matches the
current machine's network:

```console
$ ssh-profile
home
```

Use the profile name in an `ssh_config` `Match exec` predicate to select SSH
host options by profile (excerpted -- see the
[Configuration guide](https://sck.gitlab.io/ssh-profile/configuration/) for
the full pattern):

```
Match originalhost myserver exec "ssh-profile home"
    HostName 10.0.0.50
    User me

Match originalhost myserver exec "ssh-profile work-wired"
    HostName myserver.internal
    ProxyJump bastion.work
    User me.work
```

Validate the profile data file and `~/.ssh/config` references after each edit:

```sh
ssh-profile --check-config
```

## Project links

* **PyPI:** https://pypi.org/project/ssh-profile/
* **Documentation:** https://sck.gitlab.io/ssh-profile/
* **Source & issues:** https://gitlab.com/sck/ssh-profile

## License

MIT.  Created in 2026 by [Scott Karlin](https://gitlab.com/sck).
