# anasaki-code CLI

> Pull Site Code into VS Code with full types, then push, watch and publish from the terminal — from creating a token to resolving conflicts

Source: https://anasaki.live/docs/en/developers/cli

`anasaki-code` keeps your site's Site Code in a local folder so you can edit it in VS Code (with types from `anasaki.d.ts`) and sync / read logs / publish from the terminal. It needs **Node.js ≥ 20** and has no extra dependencies.

## Installing

The CLI is in the `cli/` folder of the Anasaki Studio repository:

```sh
git clone https://github.com/Kiroriya/AnasakiStudioOfficial.git
npm install -g ./AnasakiStudioOfficial/cli     # gives you the anasaki-code command
anasaki-code --help
```

Or run it without installing: `node AnasakiStudioOfficial/cli/bin/anasaki-code.mjs --help`

> [!NOTE]
> Once the `anasaki-code` package is published on npm, `npx anasaki-code …` will work without cloning.

## 1. Create a token

1. In the admin: **My account → Tool tokens → Create token**
2. Give it a name (e.g. &#34;Work laptop&#34;), choose its **lifetime** (30 days, 90 days, 1 year or never expires) and the **code** scope
3. Copy the token (`ast_…`) and keep it — **it is shown only once**

The token has your role's rights: `view_scripts` to pull files and read logs, `edit_scripts` to push, `publish_scripts` to publish. A token works only on `/api/v1/code/**` and stops working at once when it is revoked, expires or its owner changes their password.

## 2. Start a project

```sh
anasaki-code login https://example.com      # paste the token (or --token ast_...)
mkdir my-site && cd my-site
anasaki-code init https://example.com       # creates anasaki.json + tsconfig.json + .anasakiignore, then pulls
code .
```

VS Code reads `anasaki.d.ts` through `tsconfig.json` right away — every global (`site`, `db`, `log`, `mail`, `http`, `jobs`, `plugins`…) and the modules of active JavaScript plugins get autocomplete and type checking.

## 3. Edit, push and publish

```sh
anasaki-code watch                          # push on every save (300 ms debounce) and show build errors
anasaki-code publish -m &#34;Add checkout page&#34; # build → show pending migrations → ask if data may be lost → publish
```

Everything you push goes to the server's **draft** (the same draft the web editor uses); the live site changes only on `publish`.

## All commands

| Command | What it does |
| --- | --- |
| `login [--token ast_...]` | Checks the token and stores it in `~/.anasaki/credentials.json`, per site |
| `logout [site]` | Removes the stored token |
| `init [site] [--dir ]` | Creates `anasaki.json`, `tsconfig.json`, `.anasakiignore`, then `pull` |
| `pull [--force]` | Downloads the draft and `anasaki.d.ts` — files you changed locally are not overwritten (reported as conflicts) unless you pass `--force` |
| `push [--dry-run] [--delete]` | Sends the changed files in one request (all or nothing). Files deleted locally are deleted on the server only with `--delete` |
| `status` | Compares local files, the server draft and the last sync |
| `watch [--debounce ms] [--poll ms]` | Pushes once, then on every save — **never deletes files on the server** |
| `publish [-m ] [--yes]` | Builds, shows migrations, asks for confirmation if data may be lost (`--yes` skips it — required when nobody can answer) and publishes |
| `logs [--follow] [--unit ] [--level ] [--limit n]` | Shows logs (`--unit` = `site` or a JavaScript plugin's id) |
| `types` | Refreshes `anasaki.d.ts` (after adding migrations or changing plugins) |

Exit codes: `0` success · `1` error (network, authentication, usage) · `2` conflict, failed check or build error

## Project files

- **`anasaki.json`** — `{ &#34;site&#34;: &#34;https://example.com&#34;, &#34;dir&#34;: &#34;.&#34; }`, no secrets, safe to commit
- **`.anasaki/state.json`** — hashes of the last sync; don't commit it if several people share the folder
- **`.anasakiignore`** — `.gitignore`-like patterns. Only `.ts .js .mjs .json .md` are synced, and dot files, `node_modules/` and `anasaki.d.ts` / `tsconfig.json` at the root are always skipped

## Environment variables

| Variable |  |
| --- | --- |
| `ANASAKI_TOKEN` | A token used instead of the stored one — good for CI |
| `ANASAKI_LANG` / `LANG` | Messages are in Thai when the value starts with `th` (e.g. `ANASAKI_LANG=th`) |
| `ANASAKI_CONFIG_DIR` | Where `credentials.json` lives (default `~/.anasaki`) |

## Errors in VS Code's Problems panel

Build errors print as `path:line:column: error: message`, and `watch` prints `[anasaki] sync start` / `[anasaki] sync done`. Put this in `.vscode/tasks.json`:

```json
{
  &#34;version&#34;: &#34;2.0.0&#34;,
  &#34;tasks&#34;: [
    {
      &#34;label&#34;: &#34;anasaki: watch&#34;,
      &#34;type&#34;: &#34;shell&#34;,
      &#34;command&#34;: &#34;anasaki-code watch&#34;,
      &#34;isBackground&#34;: true,
      &#34;problemMatcher&#34;: {
        &#34;owner&#34;: &#34;anasaki&#34;,
        &#34;fileLocation&#34;: [&#34;relative&#34;, &#34;${workspaceFolder}&#34;],
        &#34;pattern&#34;: {
          &#34;regexp&#34;: &#34;^(.+?):(\\d+):(\\d+): (error|warning): (.*)$&#34;,
          &#34;file&#34;: 1, &#34;line&#34;: 2, &#34;column&#34;: 3, &#34;severity&#34;: 4, &#34;message&#34;: 5
        },
        &#34;background&#34;: {
          &#34;activeBegin&#34;: &#34;^\\[anasaki\\] sync start&#34;,
          &#34;endsPattern&#34;: &#34;^\\[anasaki\\] sync done&#34;
        }
      }
    }
  ]
}
```

## Conflicts

If the same file was changed both locally and on the site (someone saved in the web editor), `push` sends nothing and exits with 2:

1. `anasaki-code pull` — pulls every other file and lists the conflicting ones (your files stay)
2. Back up your files, run `anasaki-code pull --force` to take the server's files, then merge your changes back in
3. `anasaki-code push`

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| 401 | The token was revoked, expired, or the password changed — create a new token and run `anasaki-code login` |
| 403 `token scope` | The endpoint is outside `/api/v1/code/**`; any other 403 = your role lacks that permission |
| exit 2 on push | A file changed on the server after your last pull — follow the conflict steps above |
| Files reported as skipped | Unsupported extension or name (only `A-Z a-z 0-9 . _ -` in each path segment) |
