# The setup app and the ap CLI

The setup app prepares your machine, clones projects, and opens them in the editor of your choice, while the ap CLI starts applications from the terminal and connects you to the platform.

> Source: https://www.application-platform.com/en/docs/local-app/

The setup app is the platform's desktop application for macOS, Windows, and Linux ([downloads page]({{< relref "/downloads" >}})) and installs the `ap` CLI. After signing in with your Application Platform account, you see **Projects**, **Developer setup**, and **Settings**.

## Developer setup

The **Developer setup** checks your machine and installs missing tools individually or all at once, from Git and the runtimes in `.tool-versions` to editors and AI tools ([Requirements]({{< relref "local-requirements" >}})); run it before cloning your first project.

## Cloning projects

In the **Projects** area you clone a project; the app clones all repositories into the workspace folder, `~/Documents/application-platform` by default, or updates them there. It also sets up the `ap` CLI, a pre-commit hook protecting `.gitlab-ci.yml` and `env/*.generated.env`, the symlinks to `local-configuration`, and the platform extension for VS Code, Cursor, and Antigravity ([Working locally on your project]({{< relref "working-locally" >}})).

{{< docnote type="warning" >}}
On a Mac, keep the workspace folder out of iCloud-synced folders, because syncing can break Git repositories and symlinks.
{{< /docnote >}}

## Opening projects in your editor

From the **Projects** area you open a project with a click in the **default tool** from the settings; supported editors and agents are listed under [Choose your editor]({{< relref "choosing-your-ide" >}}).

## Settings

In **Settings** you choose the **default tool**, enter your Git identity (name, email address) and Git credentials, open the workspace folder or copy its path, and view the versions of app, CLI, and extension.

## Updates

The setup app checks for new versions itself; `ap cli-update check` checks the CLI, `ap --version` shows its version. Without the setup app, you install the CLI with one command, as described under [CLI and agent plugin]({{< relref "cli-and-agent-plugin" >}}).

## The ap CLI

`ap run-local` starts the application and its services from a repository root ([Starting applications]({{< relref "workspace-ubuntu-dev-scripts" >}})); `ap ports` shows the local ports, `ap doctor` checks the tools, `ap workspace info` gives an overview of project and repositories. After `ap login` you clone projects without the desktop app:

```bash
ap login
ap platform projects clone <project-slug>
```

`ap git auto-commit` stages, commits, and pushes in one step, `ap secrets edit <file>` opens an encrypted deployment configuration; sign-in, agent plugin and MCP server are covered under [CLI and agent plugin]({{< relref "cli-and-agent-plugin" >}}).

## The setup CLI ap-app

The setup CLI `ap-app` runs the same setup steps without a user interface, for example for automation:

```bash
ap-app tools status
ap-app tools install asdf-plugin-hugo
ap-app auth login
ap-app projects clone <org>/<project>
ap-app remote-dev status
```

`ap-app` covers tools, the setup app's login session, cloning, and the remote-dev agent, `ap` applications, Git hooks, the platform API, and MCP. The setup app and `ap-app` share their session (`~/Library/Application Support/application-platform/ap-app/session.json` on macOS, otherwise `~/.config/application-platform/ap-app/session.json`), the `ap` CLI signs in separately through `ap login`.