# Get started

> From installing to pulling your setup on a new machine, the steps you do once.

## What you need

- macOS or Linux
- The [GitHub CLI](https://cli.github.com), logged in with `gh auth login`
- The Claude Code setup you use now (`~/.claude`)

aisync runs no server of its own. Your setup is stored in a private repo in your GitHub account, and gh handles the GitHub login.

## Install

```sh
wget -qO- https://raw.githubusercontent.com/CreatiCoding/aisync/main/install.sh | sh
```

curl works too. The script downloads the build for your OS, checks its checksum and puts it at `~/.local/bin/aisync`.

```sh
curl -fsSL https://raw.githubusercontent.com/CreatiCoding/aisync/main/install.sh | sh
```

Keep the binary where it is: after a pull, MCP servers in `.claude.json` point at its absolute path. If you move it, run `aisync pull <profile>` again to rewrite the paths.

With Go 1.24 or newer you can build from source:

```sh
go install github.com/CreatiCoding/aisync/cmd/aisync@latest
```

> aisync is in private beta, so these commands work once the source is public.

## 1. Find hardcoded tokens first

Before uploading anything, see where your setup has plain-text tokens. This needs no login and uploads nothing.

```sh
aisync scan
```

```text
Hardcoded secrets in ~/.claude (+ ~/.claude.json):
  BLOCKS    settings.json (OPENAI_API_KEY)        sk-p…(34 chars)
  encrypt   mcp github (Authorization)            ghp_…(40 chars)
  encrypt   mcp slack (SLACK_BOT_TOKEN)           xoxb…(32 chars)
```

| Mark | Meaning | What to do |
|---|---|---|
| `encrypt` | A token in an MCP server | Nothing. It moves to the encrypted store on capture |
| `BLOCKS` | A token in a file such as settings.json or CLAUDE.md | Take it out of the file before you capture |
| `local` | A token in a file aisync never uploads | Nothing. A plain-text copy exists on this machine |

If you see `BLOCKS`, remove or move that value and scan again. See [Secrets](/en/docs/secrets/).

## 2. Log in and upload

```sh
aisync login
aisync capture default
```

`login` reuses your gh login and creates `<you>/aisync-config` as a private repo if it doesn't exist. Pass `--repo owner/name` to use another one.

`capture` shows the same scan again and, the first time, asks you to pick a passphrase. It encrypts your tokens, and you type it once on each new machine. If you lose it the stored tokens can't be recovered, so keep it in a password manager.

```text
Captured default from ~/.claude: 4 files, 3 MCP servers → you/aisync-config 62cefe5
Secrets moved to the encrypted store: github-authorization, slack-bot
```

After capture, the plain-text tokens in this machine's `~/.claude.json` are replaced with references too.

## 3. Pull on the new machine

Install aisync on the new machine, log in to gh, then:

```sh
aisync login
aisync pull default
```

The first pull asks for the passphrase once and keeps the key in the keychain after that. Files that get replaced are copied to `~/.claude/.aisync/backup/` first.

```text
default → ~/.claude
  add      file   CLAUDE.md
  replace  file   settings.json  (existing file, will be backed up)
  add      server slack
Backed up replaced files to ~/.claude/.aisync/backup/20261011-105256
Applied default at 62cefe5.
```

Restart any running Claude Code session so it loads the new MCP servers.

## 4. Day to day

Push what you changed on one machine and pull it on the other. `diff` shows what a pull would change.

```sh
aisync push default -m "add a rule"
aisync diff default
aisync pull default
```

What happens when both machines changed the same file is in [Syncing and conflicts](/en/docs/sync/).