> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start from an existing workspace

> Read a Xano workspace you already have back as Xano SDK TypeScript with init --from workspace, check the round-trip report, adopt live identities with lock import, and decide where the source of truth lives.

If your backend already runs on Xano, you do not start from an empty `xano/`. `init --from`
reads the workspace and writes it out as readable SDK TypeScript (real `table()`, `query()`
and `s.db.query(...)` calls), inside the same runnable project a plain `init` writes.

<Note>
  **On Windows or an Intel Mac?** There is no Xano Engine build for your machine yet. Wherever this
  page says `npm run xano:deploy`, run `npm run xano:deploy:ephemeral` instead: it deploys the same
  code to an ephemeral in Xano's cloud. That needs a Xano account, so sign in first
  ([Connect to Xano](/start/connect-to-xano)). See
  [where the Engine differs today](/run/xano-engine#where-the-engine-differs-today).
</Note>

## 1. Sign in

```bash theme={null}
npx @xano/sdk login
npx @xano/sdk workspace details   # the instance and workspace you are bound to
```

The pull reads the workspace your login is bound to. [Connect to Xano](/start/connect-to-xano)
covers signing in, including `--paste` for a remote shell.

## 2. Pull the workspace

```bash theme={null}
npx @xano/sdk init my-app --from workspace
cd my-app
```

`--from workspace` reads the live Xano branch. `--branch <label>` reads another one, and
`--framework` picks the frontend as it does for a new project. To add the pulled backend to an
app you already have, run `npx @xano/sdk init --from workspace` inside it instead
([Existing app](/start/existing-app) covers what gets merged).

A pull carries schema and logic only: no table rows and no stored files. Object identities
are kept, so references between objects stay intact, and a statement the SDK does not model
yet is carried over verbatim rather than breaking the pull.

## 3. Read the round-trip report

After writing the tree, `init` checks its own work: it loads the project it just wrote,
exports it, and diffs the result against the workspace. A mismatch names the object, and the
command exits `2` with the tree written but reported as unverified.

Read two things before you go further:

* **The decode report** that `init` prints, and `xano/README.md`, which lists anything that
  did not translate cleanly and any object that was already empty in the workspace.
* **`xano/.env`**, which holds the env var values the workspace carried. It is gitignored;
  `xano/.env.example` lists only the names.

A tree that passes gets its `xano/xano.lock` from that same export, so commit it with the
first commit:

```bash theme={null}
git init && git add -A && git commit -m "Pull the workspace into code"
```

Then run it on your machine:

```bash theme={null}
npm run xano:deploy
```

That deploys the pulled backend to the Xano Engine, not to your workspace.

<Warning>
  After a pull, `xano/` is your source. Promoting a release changes what the workspace runs, so
  try every change on the Xano Engine or an ephemeral first.
</Warning>

## Code you wrote yourself: adopt the live identities

If your code did not come from a pull (you wrote it by hand, or ported part of a workspace),
its objects do not yet carry the identities the workspace already serves. Without them, your
first release would create duplicates beside the existing objects. Adopt them first:

```bash theme={null}
npx xanosdk workspace export --path live.json
npx xanosdk lock import live.json --entry=xano/index.ts --yes
git add xano/xano.lock && git commit -m "Adopt live identities"
```

`lock import` records every identity in that export, by type and name, in `xano/xano.lock`.
A brand-new workspace has nothing to adopt and needs no such step.

## Decide where the truth lives

Once the workspace is code, pick one source of truth:

* **The repo.** People stop editing the workspace in the Xano editor, and every change
  arrives through a pull request and a release.
* **The workspace.** The team keeps building in the editor, and you refresh the repo from it
  with `npx xanosdk pull workspace` before each change you make in code.

[Source of truth](/ship/source-of-truth) compares the two and shows how to catch drift.

## Next

* [How it works](/start/how-it-works): the model behind the code you just pulled.
* [Deploy to Xano](/ship/overview): ship a change back to the workspace through a release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.