Skip to content

09 Example Usage

This chapter shows how to use SSH Teams in day-to-day terminal workflows by replacing direct ssh, scp, and sftp usage with the SSH Teams wrapper command.

9.1 Prerequisites

Requirement Lab Staging Production
sshteam CLI installed Required Required Required
Device registered and token valid Required Required Required
Target host already joined to team CA Recommended Required Required
Matching policy for user/principal/server Recommended Required Required
OpenSSH client tools (ssh, scp, sftp) available Required Required Required

9.2 Why Use the Wrapper

Instead of invoking OpenSSH commands directly, use the SSH Teams wrapper so certificates are issued just-in-time per connection.

Wrapper pattern:

sshteam [ssh|scp|sftp] [sshteam-flags...] [native-command-args...]

At runtime, the wrapper:

  1. Collects SSH Teams issuance flags.
  2. Calls sshteam-cli issue to mint an ephemeral certificate.
  3. Launches the native command with -i <ephemeral-key-path>.
  4. Cleans up the temporary key on exit.

If wrapper commands fail due to policy/device/certificate issues, use 12-troubleshooting-handbook.md#124-device-flow-failures and 12-troubleshooting-handbook.md#126-certificate-issuance-failures.

9.3 Basic SSH Usage

Connect to a host using SSH Teams certificate issuance:

sshteam ssh devops@app01.example.net

Pass through standard SSH options as usual:

sshteam ssh -p 2222 -L 15432:127.0.0.1:5432 devops@app01.example.net

9.4 Basic SCP and SFTP Usage

Copy a local file to a remote host:

sshteam scp ./build.tar.gz devops@app01.example.net:/tmp/

Copy from remote host to local machine:

sshteam scp devops@app01.example.net:/var/log/app.log ./app.log

Start an SFTP session:

sshteam sftp devops@app01.example.net

9.5 Common SSH Teams Flags

The wrapper forwards SSH Teams issuance flags to sshteam-cli issue.

Common flags:

  • --server <url|host[:port]>: target SSH Teams server (for example, https://teams.example.com, teams.example.com, or teams.example.com:443).
  • --provider <name>: certificate provider selection where applicable.
  • --ttl <duration>: request certificate lifetime override (subject to policy limits).
  • --insecure: allow insecure TLS behavior for lab/self-signed environments only.

Server selection notes:

  • --server accepts either full HTTPS URL or hostname form; if scheme is omitted, HTTPS is assumed.
  • If this device is registered to a single SSH Teams CA (or a default server is already configured via sshteam init), you can omit --server.

Example with explicit TTL:

sshteam ssh --ttl 15m devops@app01.example.net

Example with server omitted (single/default CA):

sshteam ssh devops@app01.example.net

9.6 Multiple SSH Teams CA

When your device is registered to more than one SSH Teams CA/server, use --server to select the intended CA for this command.

Default behavior with multiple CAs:

  • If --server is omitted, SSH Teams uses the configured default server.
  • The first successful sshteam init auto-configures the default server.
  • Additional sshteam init calls do not change the default unless --default is specified.

Use a full URL:

sshteam ssh --server https://ca-prod.example.com devops@app01.example.net

Or use hostname/host:port form (HTTPS is assumed when scheme is omitted):

sshteam ssh --server ca-dr.example.com:8443 devops@app01.example.net

Multiple-CA examples for file transfer:

sshteam scp --server https://ca-prod.example.com ./build.tar.gz devops@app01.example.net:/tmp/
sshteam sftp --server ca-dr.example.com devops@app01.example.net

Set or change the default server:

sshteam init ca-prod.example.com --default
sshteam init ca-dr.example.com:8443 --default

Check which server is default:

sshteam devices list

sshteam devices list marks the active default with [default].

9.7 Optional Shell Aliases

If you want command ergonomics close to native OpenSSH commands, define aliases:

alias ssh='sshteam ssh'
alias scp='sshteam scp'
alias sftp='sshteam sftp'

After this, standard command muscle memory works while still using SSH Teams-issued ephemeral certificates.

Operational tip:

  • Keep aliases in your interactive shell profile only; avoid forcing them in non-interactive automation scripts unless behavior is fully validated.

9.8 Pro Tip and Common Gotcha

Pro tip:

  • For automation, pin --server explicitly even when a default is configured. This removes ambiguity in multi-CA environments.

Common gotcha:

  • Teams often set convenient shell aliases for humans, then accidentally rely on them in scripts where aliases are not loaded. Keep automation commands explicit.