---
title: Setting Up Access and CLI Tooling | Shopware Community Hub
description: >-
Install and verify the sw-paas CLI, authenticate, manage Vault SSH keys and
deploy keys on Git hosts, and use the right access pattern for local work and…
canonical_url: 'https://hub.shopware.com/learn/unit/setting-up-access-and-cli-tooling'
---
# Setting Up Access and CLI Tooling
- Set up local access to Native PaaS by installing and verifying the `sw-paas` CLI.
- Authenticate the CLI, set a default context, and explain how organization, project, and application scope relate to each other.
- Connect a Git repository to a Native PaaS project using Vault-backed SSH access.
- Distinguish interactive user authentication from service account and token-based access for CI/CD and scripts.
# Setting Up Access and CLI Tooling
Native PaaS is a CLI-first platform. Before you can create projects, connect repositories, or trigger deployments, you need working local access.
In this unit, you set up that access step by step. You install the `sw-paas` CLI, authenticate your account, and connect Git through SSH so the platform can read your repository safely.
This gives you the platform access you need for the next learning units, where you will work with projects, applications, and deployments.
An important distinction already helps here: The `sw-paas` CLI manages Native PaaS resources such as projects, applications, Vault secrets, and deployments. It does **not** create the Shopware project codebase itself. You will prepare that codebase locally with Composer and Git in the next learning unit.
## Install and Verify the CLI
### Install With the Official Installer
For most setups, start with the official installer. As always, verify the current command in the [CLI documentation](https://developer.shopware.com/docs/products/paas/shopware/get-started/cli.html):
```bash
curl -L https://install.sw-paas-cli.shopware.systems | sh
```
If you need a specific version, you can pin it. The example below comes from the enablement materials, but you should replace it with the version your team standardizes on:
```bash
curl -L https://install.sw-paas-cli.shopware.systems | sh -s 0.0.30
```
If you want to install into a custom location, set `SW_PAAS_DIR` before running the installer. For example:
```bash
export SW_PAAS_DIR="$HOME/tools/sw-paas"
curl -L https://install.sw-paas-cli.shopware.systems | sh
```
### Manual Installation
If the installer is not an option in your environment, you can also install the CLI manually from GitHub:
1. Download the matching binary for your operating system and CPU architecture from the [`sw-paas` GitHub releases](https://github.com/shopware/sw-paas/releases).
2. Make the binary executable:
```bash
chmod +x sw-paas__
```
3. Move it to a directory on your `PATH`:
```bash
mv sw-paas__ /usr/local/bin/sw-paas
```
Use **WSL2** for a Linux environment. Native Windows without WSL is not the recommended path in enablement.
Also align Git **line endings** with your team (`core.autocrlf` or `.gitattributes`) so shell scripts, hooks, and YAML checked in from Windows do not pick up accidental CRLF that breaks Linux-based builds.
### Verify the Installation
After either installation path, open a **new** terminal and check that Git and the CLI are available:
```bash
git --version
sw-paas version
```
Opening a new terminal is necessary because the installer may update your shell configuration. An already open terminal does not automatically reload that change, so it may not know the new `sw-paas` path yet. If `sw-paas` is still not found afterwards, confirm that your shell config (`~/.zshrc`, `~/.bashrc`, and so on) contains the installation path. If needed, add it manually:
```bash
export PATH="$HOME/.sw-paas/bin:$PATH"
```
### WSL2 and mTLS Tunnels
The basic CLI commands work without this extra step. The WSL2 networking detail becomes important later for commands such as `sw-paas exec` and `sw-paas open service`, because they use **mTLS tunnels**.
These tunnels do **not** work reliably when WSL2 uses **NAT** networking. If WSL2 is using **NAT Networking Mode**, switch it to **mirrored** networking:
In practice, **mirrored** networking makes WSL behave more like the host network instead of hiding it behind a separate NAT layer. That gives the mTLS tunnel a more reliable network path.
1. Create or edit `%USERPROFILE%\.wslconfig` on Windows:
```ini
[wsl2]
networkingMode=mirrored
```
2. Run `wsl --shutdown`, then open WSL again. This is necessary because WSL only applies the changed networking mode after a full restart.
See the [Known Issues](https://developer.shopware.com/docs/products/paas/shopware/known-issues.html) page in the official PaaS Native documentation for the authoritative explanation.
Linux VMs with NAT-style networking can hit the same class of problem. If you need tunnels there, prefer bridged or host networking.
## Sign In to Your Account
Once the CLI is installed, the next step is to connect it to your Shopware PaaS account. Start the login flow with:
```bash
sw-paas auth
```
This opens a browser-based login flow. After success, the CLI runs against the API with your user identity. There is no self-registration. You must be **invited** to an organization first.
After login, confirm which account the CLI is using:
```bash
sw-paas account whoami
```
For scripts, `sw-paas account whoami --output json` (optionally piped through `jq`) can help capture the subject identifier an admin needs when adding users.
At this point, the CLI is authenticated and ready to work with your account.
### Set Your Default CLI Context
After authentication, set a local CLI context so you do not have to pass organization and project on every command:
```bash
sw-paas account context set
```
After that, the CLI knows which organization and project you want to work with by default.
That selection is stored locally. Typical locations are:
- `~/.config/sw-paas/` on Linux.
- `~/Library/Application Support/sw-paas/` on macOS.
- `%LOCALAPPDATA%\sw-paas\` on Windows.
Paths can vary slightly by version, so check the documentation if needed.
### Work Across Multiple Organizations
So far, the examples assume that you work in one organization. In practice, one account can belong to multiple organizations, and access can be granted at organization, project, or application level.
One email can access multiple organizations. If that applies to you, list the available organizations first and then select the context you want to work in. Exact flags evolve, so follow the current documentation.
Human user access is managed through `sw-paas account user`. Users can also request access themselves, and account admins can review those requests. For automation, use service accounts instead of tying long-running jobs to a human user.
The exact user-management commands, identifiers, and access workflows can change as Native PaaS evolves.
If you add users, review access requests, or set up service accounts, use these documentation pages for the exact commands and required identifiers:
- [Organization](https://developer.shopware.com/docs/products/paas/shopware/fundamentals/organization.html)
- [Account](https://developer.shopware.com/docs/products/paas/shopware/fundamentals/account.html)
The diagram below summarizes how organization, project, and application relate to each other:
## Connect Git With SSH Keys
Deployments are Git-driven. That means the platform must be able to clone your repository.
The safest pattern is to store the SSH key in Vault and register the public key on your Git host, instead of embedding credentials in YAML.
The diagram below shows how Vault, your Git host, and the platform work together in that setup.
1. Create an SSH key secret in Vault, e.g.:
```bash
sw-paas vault create --type ssh
```
2. Add the public key to your Git host as a deploy key. Read-only access is enough for deployment:
**GitHub:** Settings → Deploy keys
**GitLab:** Settings → Repository → Deploy keys
**Bitbucket:** Repository settings → Access keys
3. Create a project that points to the SSH remote:
```bash
sw-paas project create --name "my-shopware-app" --repository "git@github.com:username/repo.git"
```
This point matters because repository scope defines how applications are grouped on the platform.
A project maps to one Git repository. Multiple applications (staging, production, ephemeral) live under that project and deploy different commits from the same repository. In the enablement model, this is not split into separate repositories such as “frontend” and “backend”.
## The Basic Deployment Flow
At this point, you have the local prerequisites in place. The next step is to look at the basic deployment flow.
You do not need to use these commands in depth yet, but you should understand what each one does:
```bash
sw-paas application create
sw-paas application deploy create
sw-paas watch
```
**Explanation:**
- `sw-paas application create` creates an application on the platform.
- `sw-paas application deploy create` starts a deployment for that application.
- `sw-paas watch` streams deployment events such as queued → base infra → shop infra → Shopware deploy → success or failure.
You will work through these commands in more detail in the next learning unit. For now, the important point is the order: create an application, deploy a commit, and watch the rollout.
## Use Service Accounts and Tokens for Automation
Browser login works well on a developer machine, but it is impractical in CI/CD. For GitLab CI, GitHub Actions, or similar automation, use token-based access.
There are two access patterns:
- **Personal access tokens** belong to a human user. They are useful for local non-interactive work or short-lived scripts, but they inherit the permissions of that user.
- **Service account tokens** belong to a machine identity. They are the better default for CI/CD because their grants can be scoped to the automation task.
For a shared pipeline, avoid tying the workflow to one person's account. If that person leaves the team, rotates credentials, or loses permissions, the pipeline can break even though the project itself did not change.
The better pattern is to create a service account, grant it only the permissions the pipeline needs, generate a token for that service account, and store that token in the CI secret store.
Exact subcommands follow the current CLI help and [Account fundamentals](https://developer.shopware.com/docs/products/paas/shopware/fundamentals/account.html). The basic idea is simple: pass a token to `sw-paas` so the pipeline can authenticate without a browser.
Typical patterns:
```bash
sw-paas --token "YOUR_TOKEN" account whoami
# or
export SW_PAAS_TOKEN="YOUR_TOKEN"
```
For service accounts, the workflow uses the `account service-account` commands to create the machine identity and manage its grants. The token itself is then created for that service account.
A personal access token inherits the **permissions of the user who created it**, except it **cannot create further tokens**. A service account token authenticates as the service account and is limited by the grants assigned to that service account.
For automation, prefer a service account with the **least privilege** that still allows the pipeline’s job. Revoke tokens that are leaked or no longer needed with `sw-paas account token revoke --token-id ` (see [Account](https://developer.shopware.com/docs/products/paas/shopware/fundamentals/account.html)).
Store tokens in your CI secret store or team vault, **never** in the repository. Prefer environment variables and interactive prompts over pasting secrets on the command line, where they may be logged in shell history.
If your security model requires project-level SSH keys, you can create them with `sw-paas vault create --type ssh --project `. Org-level keys remain the default pattern.
## Check Your Understanding
Use these questions to check two core ideas from this unit: How automation should authenticate, and how projects, applications, and short-lived environments fit together.
Your team needs a GitHub Actions workflow that runs `sw-paas application deploy create` on every merge to `main` for a shared production application. Which approach should you use?
The tech lead creates a personal access token, stores it as `SW_PAAS_TOKEN`, and the workflow runs as that person
Create a service account, grant it only the deploy permissions the workflow needs, generate a token for that service account, and store it as `SW_PAAS_TOKEN`
Run `sw-paas auth` as the first workflow step so the CI runner can log in through the browser on every build
Your `acme/storefront` repository is already deployed as the production application for the Storefront project. A developer wants to test a feature branch on real infrastructure without touching production. What is the intended pattern?
Create a second project pointing at the same `acme/storefront` repository, then create one application in it for the feature branch commit
Create a second application inside the existing Storefront project, deploy the feature branch commit there, and make it ephemeral so it can be cleaned up automatically
Fork `acme/storefront` to a new repository, register the fork as a new project, and create an application there
## Summary
In this learning unit, you learned:
- How to install and verify the `sw-paas` CLI.
- How to authenticate the CLI, confirm your identity, and set a local context.
- How organizations, projects, and applications relate to each other.
- How to connect one Git repository to one project with SSH deploy keys stored in Vault.
- How to use service accounts and tokens for CI/CD when browser login is not possible.
With this knowledge, you can set up access with confidence and understand how local CLI setup, authentication, Git access, and automation fit together on Native PaaS.
You can also separate the two responsibilities more clearly now: `sw-paas` is the CLI for platform access and platform operations, while the Shopware project itself is prepared locally in your repository.