The stacktape login command authenticates the Stacktape CLI on the current system. For local development, run it interactively: you approve the sign-in in your browser, and the CLI keeps the local auth state. For CI/CD, use a dedicated Stacktape API key stored in your CI provider's secret store.
Usage
In interactive mode (the default), the command asks how you want to sign in:
- Sign in with the browser (recommended). The CLI prints an address and a code, and opens the address in your browser. Sign in to the Stacktape Console there with any sign-in method, or create an account. Check that the Console shows the same code as your terminal, then approve. The CLI continues by itself. Never approve a code that someone else sent you.
- Enter API key manually. Paste an API key created in the Stacktape Console.
Over SSH, in a container or on a machine without a browser, the browser sign-in still works: open the printed address on any device. Pass --no-browser to only print it. If your account belongs to several organizations, the CLI asks which one this machine works in. After successful authentication, Stacktape displays your user name and organization.
For CI/CD, prefer setting STACKTAPE_API_KEY as a masked secret in the runner environment. If you need an explicit login step, pass the key from the CI secret variable. Never paste an API key into an AI chat, issue tracker, shell transcript, or log.
You can create CI keys from the Stacktape Console's API keys page. Manual API keys are bearer secrets and should be treated as shown-once credentials.
What happens during login
Stacktape performs these steps when you run login:
- Authenticates you — through the browser sign-in, which the CLI exchanges for a CLI session for the organization you choose, or by verifying the API key supplied by a CI secret. The short-lived sign-in from the browser is never stored.
- Stores local auth state — keeps the CLI session in the operating system's credential store on Windows (Credential Manager) and Linux (Secret Service). Where that store is unavailable, as is common in WSL, SSH sessions and containers, the session is kept in
~/.stacktape/persisted-state.json, readable only by your user. SetSTACKTAPE_CREDENTIAL_STORE=fileto always use the file, for example on a machine whose credential store asks for a password on every command. - Verifies access — calls the Stacktape API to confirm your user, organization, and permissions.
- Displays your identity — prints your user name and the organization the current auth state belongs to.
On macOS, the CLI always uses ~/.stacktape/persisted-state.json, not the Keychain. The Keychain ties each item to the signature of the program that created it, and released Stacktape binaries are not yet signed with a stable identity. Every CLI update would then ask you to allow access again, and unattended runs, such as the MCP server or stacktape dev, would wait until someone answers. As on other systems, the file is readable only by your user.
If the API key is invalid, Stacktape clears the key it attempted to save and reports an authentication error.
An interactive login creates a CLI session for the organization you choose. It ends 90 days after login, or after 30 days without use, whichever comes first; the CLI then asks you to run stacktape login again. stacktape logout ends it immediately. Console-made API keys for CI keep the expiration chosen when they were created.
The login command itself does not require an existing API key — it is one of the commands that can run without prior authentication.
Non-interactive login
For CI/CD pipelines and automated scripts, set STACKTAPE_API_KEY as a masked CI secret. The CLI can read this environment variable directly, so an explicit login step is often unnecessary. If your workflow does use login, pass the key from the secret variable and combine with --agent for programmatic output.
Do not hardcode the key in workflow YAML. Reference the CI secret.
Flags reference
stacktape loginCLI options--api-keystringAPI Key
Your Stacktape API key. Use this only in your own terminal or CI secret store. Do not paste API keys into chat transcripts, shell history, or logs. For local interactive use, prefer stacktape login.
--aws-accountstringAWS Account
The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.
Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.
-h, --helpstringShow Help
If provided, the command will not execute and will instead print help information.
--log-level"info" | "debug" | "error"Log Level
The level of logs to print to the console.
info: Basic information about the operation.error: Only errors.debug: Detailed information for debugging.
--no-browserbooleanNo Browser
If true, prints the address instead of opening a browser: init still starts the wizard, and login still waits for you to approve the sign-in. Use this when the browser you want is not this machine's default, on another device, or behind a forwarded port.
-p, --profilestringAWS Profile
The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.
For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
Examples
Interactive login
Run login with no flags to start the interactive authentication flow. Choose the browser sign-in, or enter an API key manually.
Login with an API key in CI
Pass the API key directly, typically from a CI secret or environment variable.
Verify your identity after login
After logging in, use whoami to verify your local Stacktape CLI authentication state and display the current user, organization, connected AWS accounts, and accessible projects.
Switch to a different user or organization
For local development, run stacktape login again and choose the user or organization you want to use. In CI, update the STACKTAPE_API_KEY secret to a key from the target organization.
Related commands
logout— removes Stacktape authentication state from the current system.whoami— displays the current user, organization, and connected AWS accounts.org create— creates a new organization and returns organization credentials.org list— lists all organizations accessible with your current user.
login FAQ
Where do I find my Stacktape API key?
Create CI/API keys from the Stacktape Console's API keys page. Manual keys are scoped to an organization, expire by default, and are shown only once. See API keys for details on managing keys.
Do I need an explicit login step in CI/CD?
Usually no. If you store a dedicated API key as a CI secret and expose it as STACKTAPE_API_KEY, the CLI reads that environment variable directly, so commands like deploy work without a separate login step. If your workflow does use login, pass the key from the secret variable and combine with --agent for output optimized for programmatic consumption. See the custom CI/CD guide for full pipeline setup.
What happens if I log in with an invalid API key?
If verification fails during login, Stacktape clears the API key it attempted to save and reports an authentication error. You can then retry with the correct key.
How do I switch between organizations?
For local development, run stacktape login again and choose the desired account or organization. For CI, create a key in the target organization and update the STACKTAPE_API_KEY secret. Use org list to list organizations accessible with the current Stacktape user.
Does login expire?
Yes. A CLI session from an interactive login ends 90 days after login, or after 30 days without use, whichever comes first. Manual API keys used in CI expire according to the key's expiration setting. Use logout to end the CLI session and remove local auth state.
Does login connect my AWS account?
No. The login command only authenticates the Stacktape CLI with Stacktape. AWS account connection is separate from login; see connecting your AWS account for details. Deploying is handled by deploy.
Should team members share one API key?
No. Use a separate key per integration point and prefer individual interactive login on developer machines. Sharing a key makes attribution, rotation, and revocation harder. Treat local auth state as credential material — don't read it into chat, copy it into scripts, or use it to hand-build STACKTAPE_API_KEY values — and remove it with logout when no longer needed.