Skip to main content

Authentication

tcb login logs you in to your Tencent Cloud account and authorizes CloudBase CLI to operate your CloudBase resources. Most commands prompt you to log in first when no valid credential is found.

Which Login Method to Use​

ScenarioRecommended commandNotes
Local development (default)tcb loginDevice code flow; prints a link and user code, and opens the browser automatically
International accounttcb login --intl trueAlso persists the site setting
Remote server / SSHtcb loginDefault device code flow; no port forwarding needed
Container / headless / AI Agenttcb loginWithout a browser, only the link and user code are printed
Non-interactive CI/CDtcb login --apiKeyId <SecretId> --apiKey <SecretKey>Account-level Cloud API key
Environment-level long-term credentialtcb login --cloudbase-api-key <key> -e <envId>Scoped to the specified environment
Temporary keytcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>For short-lived authorization
Local machine, local callbacktcb login --flow webCallback received on local 127.0.0.1, no user code needed
Self-hosted authorization servicetcb login --endpoint <url>Device code flow only

Local Login (Default)​

Run the following command in your terminal:

tcb login

The CLI uses device code authorization (OAuth 2.0 Device Authorization Grant, RFC 8628) by default. It does not require the terminal that starts the login and the browser that confirms it to be on the same machine:

  1. The CLI prints an authorization link (verification_uri) and a user code (user_code), and tries to open the browser
  2. Confirm the authorization in the browser (if the browser does not open, copy the link manually)
  3. The CLI polls for authorization status and saves the credential once complete

If a valid credential already exists, tcb login returns immediately with "You are already logged in" and does not run the authorization flow. Run tcb logout first to switch methods or accounts.

Local Callback Authorization​

On a machine with a graphical environment, the CLI can open the browser and complete authorization through a local callback, so you do not need to enter the user code manually:

tcb login --flow web

In this mode, the CLI starts a temporary HTTP server on a random local port, and the browser delivers the authorization result to http://127.0.0.1:<port>. It therefore requires the machine to both open a browser and receive that local callback (the default timeout is 10 minutes). For remote servers, containers, and headless environments, use the default device code flow instead.

💡 --flow accepts device (default) and web. TCB_NO_BROWSER=true only takes effect with --flow web, where it prevents the CLI from opening the browser automatically; the device code flow does not read this variable.

Cloud API Key Login​

If you already have a Tencent Cloud Cloud API key, log in interactively:

tcb login --key

Enter your SecretId and SecretKey when prompted. You can create or view keys on the Cloud API Key Management page.

⚠️ Security notice: a Tencent Cloud API key can operate all Tencent Cloud resources under your account. Store it securely and rotate it regularly; delete old keys promptly after rotation.

Remote Server and SSH​

Use the default device code flow:

tcb login

Copy the authorization link and user code printed in the terminal, open them on your local machine or any device with a browser, and confirm the authorization. The CLI polls for the result automatically. No port forwarding or local callback is required.

Containers, Headless Environments, and AI Agents​

The device code flow does not depend on a browser or a local callback, which makes it suitable for:

  • Docker / Kubernetes containers and servers without a graphical interface
  • Agents, CI runners, and other automation environments
  • AI coding assistants (e.g., Claude Code, OpenAI Codex) that invoke CloudBase CLI through MCP tools or scripts
tcb login

Without a browser, the attempt to open one fails and is ignored; the authorization link and user code are still printed. After you confirm the authorization remotely, the CLI completes the login automatically. TCB_NO_BROWSER=true only applies to --flow web, so it is not needed in headless environments.

CI/CD and Non-interactive Login​

Cloud API Key (Account-level)​

Pass your Tencent Cloud Cloud API key directly with --apiKeyId and --apiKey. This is suitable for scripts and pipelines:

tcb login --apiKeyId <SecretId> --apiKey <SecretKey>

For a temporary key, pass --token as well:

tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>

⚠️ An account-level key can operate all Tencent Cloud resources under your account. Store it in your CI secrets, never in the repository; rotate it regularly and delete old keys promptly.

Environment-level API Key​

Use a CloudBase environment-level long-term credential, which is scoped to a single environment and is better for isolated authorization:

tcb login --cloudbase-api-key <key> -e <envId>

You must specify the environment with -e/--env-id. For how to create a key, see API Key Management.

GitHub Actions Example​

- name: Login to CloudBase
  run: npx @cloudbase/cli login --cloudbase-api-key ${{ secrets.CLOUDBASE_API_KEY }} -e ${{ secrets.CLOUDBASE_ENV_ID }}

International Site Login​

For an international account, specify the site explicitly when logging in:

tcb login --intl true
  • --intl true makes this login use the international site immediately (both the authorization page and the OAuth endpoint switch) and persists the site setting, so subsequent commands default to the international site
  • To switch back to the domestic site: tcb login --intl false, or tcb config set isIntl false
  • Alternatively, run tcb config set isIntl true before running tcb login
  • Site precedence: --intl > config file isIntl > env var TCB_IS_INTL > domestic site (default)
  • Site and region are independent: switching sites does not change the region. International environments are usually in Singapore; add -r ap-singapore when a command needs a region (e.g., tcb env list -r ap-singapore)

Custom Authorization Endpoint​

Enterprise users can point device code authorization to a self-hosted service:

tcb login --endpoint https://your-auth-server.example.com

The CLI uses the specified endpoint and calls /device/code and /token in sequence to obtain credentials. This option only takes effect with --flow device (the default). The self-hosted service must comply with the CloudBase CLI Device Flow protocol. See Device Code Authorization Overview and Enterprise Self-built Device Code Authorization Service for details.

Verify Login Status​

tcb env list

If the command lists your environments, the login succeeded. If it reports that you are not logged in, the credential has expired, or the list is empty, run tcb login again. For international accounts, also confirm the region parameter (see International Site Login).

Logout and Switch Accounts​

tcb logout

tcb logout clears the local credential (including project-level credentials) and the current environment record. To switch accounts, log out and then run tcb login again.

Credential Storage and Security​

  • The login credential is stored in auth.json under the CLI config directory, by default ~/.config/.cloudbase/ (respects XDG_CONFIG_HOME)
  • When you log in with an environment-level API Key, the credential may be written to project-level storage (matching the project directory used at login)
  • auth.json contains identity credentials. Never commit it to a repository or share it with others
  • Prefer injecting long-term keys through CI secrets or environment variables instead of hard-coding them in scripts or config files

FAQ​

Login succeeds but tcb env list is empty​

  • No environment has been created under the account yet. Create one in the console
  • For an international account without a region: try tcb env list -r ap-singapore
  • The sub-account may lack permissions. See Sub-account Login Instructions

The browser cannot be opened or the authorization page is unreachable​

Use the default device code flow and copy the link and user code printed in the terminal. TCB_NO_BROWSER=true has no effect on the device code flow; it only applies to --flow web.

--flow web callback fails​

This mode requires the local machine to reach a random 127.0.0.1 port. On remote servers, in containers, or when ports are restricted, use the default --flow device instead.

Logged in but receives a permission error​

Check the account and environment ownership. An environment-level API Key can only operate the environment specified at creation, while an account-level key is limited by CAM permission policies.