Authentication

Before you can push or pull sessions, you need to authenticate with the CodeTeleport API. The CLI supports two login methods: GitHub OAuth and email/password.

Interactive login

Run codeteleport auth login with no flags to get an interactive prompt:

codeteleport auth login

How do you want to log in?
  1) GitHub
  2) Email & Password
> _

GitHub OAuth

The recommended way to log in. Pass --github to skip the prompt:

codeteleport auth login --github

1. A local callback server starts on a random port.
2. Your default browser opens the GitHub authorization page.
3. After you approve, GitHub redirects back to the local server with a token.
4. The CLI exchanges the token for an API key and saves it.

Opening browser for GitHub login...
If the browser doesn't open, visit: https://api.codeteleport.com/v1/auth/github?cli_port=54321

Logged in via GitHub
Device: bobs-laptop
API: https://api.codeteleport.com/v1
Config saved to ~/.codeteleport/config.json

Tip

If the browser doesn’t open automatically (e.g., in an SSH session), copy the URL from the terminal and paste it into any browser that can reach GitHub. The callback URL points to 127.0.0.1, so the browser must be on the same machine.

Email and password

Use --email to log in with credentials:

codeteleport auth login --email

Email: bob@example.com
Password: ********

Logged in as bob@example.com
Device: bobs-laptop
API: https://api.codeteleport.com/v1
Config saved to ~/.codeteleport/config.json

Creating a new account

Pass --register to create an account and log in at the same time:

codeteleport auth login --register

Email: bob@example.com
Password: ********

Account created for bob@example.com
Logged in as bob@example.com
Device: bobs-laptop
API: https://api.codeteleport.com/v1
Config saved to ~/.codeteleport/config.json

Pointing to a different API server

Use --api-url to authenticate against a development or self-hosted server instead of production:

codeteleport auth login --github --api-url http://localhost:8787/v1

This is useful when running the CodeTeleport API locally during development. The URL is saved to your config file, so all subsequent CLI commands will use it.

How tokens work

Authentication uses a two-step process:

Step	Token type	Format	Lifetime
Login	JWT	Standard JSON Web Token	Short-lived (minutes)
CLI operations	API token	ctk_live_...	Long-lived (until revoked)

1. When you log in (via GitHub or email), the server issues a short-lived JWT.
2. The CLI immediately uses that JWT to create a device-scoped API token (ctk_live_...).
3. The API token is saved to ~/.codeteleport/config.json and used for all subsequent requests.
4. The JWT is discarded — only the API token persists.

The API token is hashed (SHA-256) on the server side. If the config file is compromised, you can revoke the token from the dashboard without affecting other devices.

Logging out

To remove local credentials:

codeteleport auth logout

Logged out. Config removed.

This deletes ~/.codeteleport/config.json. It does not revoke the API token on the server — do that from the dashboard if needed.

Config file

After login, your credentials are stored at ~/.codeteleport/config.json with 600 permissions (owner read/write only). See Configuration for details on the file format and fields.

Full CLI reference

For all auth subcommands and flags, see the auth CLI reference.