tcloud

Profile registry and one-approval multi-account SSO login for the Tencent Cloud CLI (tccli).

Independent project, not affiliated with or endorsed by Tencent. "Tencent Cloud" is a trademark of Tencent.

Use at your own risk. tcloud handles cloud credentials and is provided "as is", without warranty of any kind. See LICENSE, sections 7 and 8. Read the code, and try it against non-production accounts first.

tccli has no native profile registry. A profile's UIN, role and region only exist inside ~/.tccli/<profile>.credential, and only after a successful login — so there is nowhere to write down "these are my accounts" before you have already logged into them.

tcloud adds the missing layer: a declarative registry at ~/.tccli/accounts.conf that lists every account you can reach, and a driver that turns those declarations into the right tccli calls.

$ tcloud ls
PROFILE               SSO        UIN           ENV         REGION         STATUS    DETAIL
app-dev               myorg      2000xxxxxxxx  dev         ap-singapore   ACTIVE    11h51m left (session 11h51m)
egress-prod           myorg      2000xxxxxxxx  prod        ap-singapore   REFRESH   creds expired — run `tcloud refresh`
audit                 otherorg   2000xxxxxxxx  shared      ap-singapore   EXPIRED   session estimate lapsed

Why it exists

Three problems, each of which costs a browser round trip to hit:

1. One login per account. tccli sso login handles a single profile per invocation and makes you pick the account from an interactive menu. N accounts meant N browser approvals.
2. No record of what exists. Nothing on disk says which accounts you can reach until you have logged into each one, so onboarding a new org is archaeology.
3. Credentials that expire quietly. tccli's auto-refresh never fires (see tccli quirks), so sessions lapse and every command starts failing at once.

tcloud fixes all three by relying on one fact tccli hides: the SSO LoginToken is realm-wide, not account-scoped. Account selection happens client-side, after the token is issued. So one approval can mint credentials for every account in that realm. It only ever uses roles your SSO administrator has already granted you.

Install

Requires Python 3.10+ on macOS or Linux. Supports the international Tencent Cloud site (tencentcloudssointl.com) only; the China site is not supported. Installing brings a supported tccli, and tcloud uses that copy rather than whatever is on PATH:

pipx install tcloud-sso

From source:

git clone https://github.com/Xeshredemption/tcloud-sso.git
pipx install ./tcloud-sso

Then create your registry:

cp accounts.conf.example ~/.tccli/accounts.conf

Real UINs are discovered, not guessed — see Registering a new org.

Tested on

• The Tencent Cloud international site (tencentcloudssointl.com) only. The China site is not supported.
• Live, against real accounts: macOS (arm64, Python 3.12) and Linux (Debian arm64, Python 3.10). Covered: multi-realm SSO login, refresh, discover, identity, logout, and every scanner including sub-commands.
• CI: offline tests on Ubuntu and macOS, Python 3.10 and 3.14.
• Windows is not supported.

The registry

~/.tccli/accounts.conf is INI, read by tcloud only — tccli never sees it.

[defaults]
role   = ReadOnly
region = ap-singapore

[profile app-dev]
uin      = 200000000001
env      = dev
auth_url = https://tencentcloudssointl.com/myorg/login

Profile names may use letters, digits, ., _ and -.

[defaults] applies to every profile unless overridden. auth_url is deliberately not defaulted — with more than one org, an inherited default silently authenticates a new entry against the wrong realm. Leaving it required means a forgotten auth_url fails loudly instead of succeeding wrongly.

Realms

The org slug in the SSO URL (https://tencentcloudssointl.com/**myorg**/login) is the realm name. It is the unit of authentication: one approval covers one realm, however many accounts sit behind it. --sso myorg selects by it, and tcloud ls shows it in the SSO column so the valid values are discoverable.

Commands

Registering a new org

A profile needs a uin, but a UIN is only knowable after an approval. discover is that step, made repeatable:

tcloud discover https://tencentcloudssointl.com/myorg/login

One approval, then for every account behind that realm it prints the UIN, display name, the roles actually available in that account, and a paste-ready block:

ACCOUNT              UIN           PROFILE  ROLES
app-dev              200000000001  -        ReadOnly
egress-prod          200000000002  -        ReadOnly, Administrator

· not in ~/.tccli/accounts.conf — paste and rename to taste

[profile app-dev]
uin      = 200000000001
auth_url = https://tencentcloudssointl.com/myorg/login
role     = ReadOnly

Roles are listed per account because a wrong role name is not caught until login — i.e. after the browser approval has already been spent on it. Accounts already in the registry are marked rather than re-suggested.

Logging in

tcloud login --all              # every realm: one approval each
tcloud login --sso myorg        # one realm, one approval, all its profiles
tcloud login --sso a --sso b    # repeatable
tcloud login app-dev            # a single profile (costs its own approval)

--all and --sso fan one approval out across every profile in the realm. A failure after approval is per-profile, never fatal — aborting would cost the survivors another round trip. An approval nobody acts on gives up after 10 minutes (--timeout SEC, 0 to wait forever).

A bare profile name shells out to tccli and spends a full approval on that one profile. --sso myorg is strictly cheaper, even for a single-account realm.

Profiles with env = prod are shown in red by tcloud ls and tagged [prod] in login output.

Refreshing without a browser

The login token outlives the role credentials derived from it and is stored on disk, so extending a session needs no approval at all:

tcloud refresh --sso myorg      # re-mint that realm
tcloud refresh --all
tcloud refresh app-dev

Profiles are grouped by token so one verification covers the whole set, and a dead token is reported once instead of as N identical errors. tcloud ls distinguishes REFRESH (recoverable by this command) from EXPIRED (needs a browser).

Scope: the three ways to say "which"

login, refresh and logout all route through one selector, so these mean the same thing in each (ls takes --sso):

--all and --sso are mutually exclusive; combining either with a profile name is an error; an unknown realm dies listing the known ones.

Identity and teardown

tcloud who                  # live GetCallerIdentity for every profile
tcloud who app-dev
tcloud logout app-dev       # delete that profile's local credential file
tcloud logout --sso myorg   # or a whole realm (also --all)

who makes a real API call per profile rather than trusting the credential files — use it to prove a login worked, not just that a file was written.

logout is local only. It deletes files and tells Tencent nothing, so a login token copied before logout stays usable until it expires. See SECURITY.md.

Resource scanners

tcloud cvm ls                       # first profile in the registry
tcloud vpc ls --all --home-region   # every profile, its configured region only
tcloud tke nodes --cluster-id cls-xxxx
tcloud stock ls --charge SPOTPAID --zone ap-singapore-2

Shared flags: --profile NAME (repeatable), --all, --region (repeatable), --home-region to skip the all-region fan-out, --state to filter, --json, --workers N.

They all default to the first profile in the registry, not to everything — --profile or --all widens it.

Every scan prints its denominator:

0 vpc(s) from 20 profile×region probe(s), 0 error(s)

An empty fleet and a failed scan must never look alike.

Layout

Nothing secret lives in this repo. Real UINs, account names and credentials stay in ~/.tccli/, which .gitignore keeps out regardless.

Security

Credential files are owner-only, profile names and SSO urls are validated, and nothing is sent anywhere except Tencent. The threat model, and how to report a vulnerability, are in SECURITY.md.

How this was built

Developed with AI assistance (Claude Code). The code was reviewed by AI, not by a human. An AI code review of the whole tool found nine issues, and each one was fixed with a regression test. The offline test suite covers every change, a contract test pins the tccli-private functions it relies on, and the scanners were checked against live Tencent Cloud accounts before release. Use at your own risk: see the notice at the top.

Contributing

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE.