Skip to content

Example Usage

This guide shows how SSH Teams fits into your everyday terminal work. You can keep using familiar commands like ssh, scp, and sftp, and let SSH Teams handle the certificates automatically.

What You Need First

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

Why Use the Wrapper?

The sshteam command wraps around OpenSSH so you do not have to manage keys or certificates yourself.

Pattern:

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

When you run it, SSH Teams:

  1. Gathers the connection details.
  2. Issues a short-lived certificate with sshteam issue.
  3. Runs the native command with the temporary key.
  4. Cleans up the key when the command finishes.

If something goes wrong with the wrapper, see the Troubleshooting Handbook or Certificate Issuance Failures.

Basic SSH Connections

Connect as usual, but start with sshteam:

sshteam ssh devops@app01.example.net

You can pass normal SSH options straight through:

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

Copying Files

Copy a local file to a remote server:

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

Copy a file back to your machine:

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

Start an SFTP session:

sshteam sftp devops@app01.example.net

Common SSH Teams Flags

These flags control how the certificate is issued:

  • --server <url|host[:port]> — pick the SSH Teams server, for example https://teams.example.com or teams.example.com:443.
  • --provider <name> — choose a certificate provider if your setup has more than one.
  • --ttl <duration> — request a shorter lifetime, such as 15m. The server policy may override this.
  • -I, --ignore-ssl-trust — allow self-signed or untrusted TLS. For lab use only.

If you registered your device with a single SSH Teams server, you can usually leave out --server.

Example with a custom lifetime:

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

Example without --server when you have a default:

sshteam ssh devops@app01.example.net

Working With Multiple SSH Teams Servers

If your device is registered with more than one server, use --server to pick which one to ask for a certificate.

  • The first sshteam init you run sets the default server.
  • Later sshteam init calls do not change the default unless you add --default.

Changing the Default Server

Run sshteam init <server> --default to switch defaults at any time.

Use a full URL:

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

Or just a hostname. HTTPS is assumed if you leave out the scheme:

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

Multiple-server file transfers look the same:

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

Check your default server:

sshteam devices list

The default is marked with [default].

Optional Shell Aliases

If you want ssh, scp, and sftp to keep feeling native, add aliases:

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

After that, your muscle memory still works, but every connection uses a fresh SSH Teams certificate.

Aliases in Scripts

Keep aliases in your interactive shell profile. Scripts usually do not load aliases, so keep automation commands explicit.

Tips and Common Gotchas

Pin the Server in Automation

Even if you have a default server, scripts should use --server so they do not pick the wrong one in multi-server environments.

Scripts Cannot See Your Aliases

A common surprise is relying on shell aliases inside scripts. Write out the full sshteam ssh command in automation.