Skip to main content
pdd sessions manages the remote PDD sessions associated with your PDD Cloud account. Remote sessions are created automatically when you run pdd connect while authenticated, and are deregistered when the server shuts down gracefully. Use pdd sessions to inspect active sessions and manually remove any orphaned ones.

​
Usage

pdd sessions SUBCOMMAND [OPTIONS]

​
Subcommands

​
sessions list

List all active remote sessions associated with your authenticated account. 
pdd sessions list [OPTIONS]
​
--json
boolean
default:"false"
Output sessions as JSON instead of a formatted table. Useful for scripting.
The table output includes the following columns:
ColumnDescription
SESSION IDTruncated unique identifier for the session
PROJECTProject name associated with the session
CLOUD URLRemote access URL via PDD Cloud
STATUSSession status: active or stale
LAST SEENTimestamp of the last heartbeat
# Human-readable table
pdd sessions list

# Machine-readable JSON
pdd sessions list --json

​
sessions info

Display detailed information about a specific session. 
pdd sessions info SESSION_ID
​
SESSION_ID
string
required
The unique identifier of the session to inspect. Use pdd sessions list to find session IDs.
Displays all available session metadata including project name, cloud URL, status, and last heartbeat time. 
pdd sessions info abc12345

​
sessions cleanup

Deregister one or more remote sessions. 
pdd sessions cleanup [OPTIONS]
​
--stale
boolean
default:"false"
Remove only stale sessions (those with no recent heartbeat).
​
--all
boolean
default:"false"
Remove all sessions for the current user, including active ones.
​
--force
boolean
default:"false"
Skip the confirmation prompt before removing sessions.
When neither --stale nor --all is specified, the command runs in interactive mode: it displays the session list and prompts you to enter session numbers, stale, or all. 
# Remove only stale sessions
pdd sessions cleanup --stale

# Remove all sessions without confirmation
pdd sessions cleanup --all --force

# Interactive cleanup (select sessions to remove)
pdd sessions cleanup

​
Session lifecycle

Sessions are managed automatically:
  1. Created — pdd connect registers a session with PDD Cloud when authenticated (unless --local-only is passed).
  2. Heartbeat — The running server sends periodic heartbeats to keep the session marked as active.
  3. Deregistered — The session is removed when pdd connect is stopped gracefully with Ctrl+C.
If a pdd connect instance is terminated ungracefully (e.g., killed or a crash), the session remains in a stale state in PDD Cloud. Use pdd sessions cleanup --stale to remove these orphaned sessions.

​
Authentication requirement

All pdd sessions subcommands require an active PDD Cloud login. Run pdd auth login first if you are not authenticated. 
pdd auth login
pdd sessions list

​
Examples

# View all active sessions
pdd sessions list

# Check the status of a specific session
pdd sessions info abc12345

# Clean up stale sessions after an ungraceful shutdown
pdd sessions cleanup --stale

# Remove everything (e.g., before switching projects)
pdd sessions cleanup --all --force
  • pdd connect — Creates and manages sessions; use --local-only to skip session registration.
  • pdd auth — Authenticate with PDD Cloud before using session management.

Build docs developers (and LLMs) love

Get started for freeTalk to us