---
title: "Workspace"
description: "Pull an organization into files, review the diff, and push it back."
---

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

# Workspace

For anything beyond a single call, work a local workspace rather than issuing
commands one at a time. `pull` materialises the organization into reviewable
files, `push` reports what applying them would change, and `--apply` commits it.

```sh
minima pull
minima push
minima push --apply
minima push minima/entities --apply
```

**`push` writes nothing without `--apply`.** Positional paths narrow the plan to
those files or directories.

## What pull writes

`pull` writes a `minima/` directory of `.jsonc` files, plus a `.minima/` cache
it uses as the baseline for the next pull:

```
minima/
├── entities/<Type>/<slug>.jsonc
├── entity-types/<key>.jsonc
├── categories/<slug>.jsonc
├── images/<slug>.jsonc
└── sites/<site>/
├── site.jsonc
├── pages/<slug>.jsonc
├── articles/<slug>.jsonc
└── menus/<slug>.jsonc
```

The files are JSONC, so comments you add survive a later pull. Anything under
`sites/` that does not match one of those shapes is reported rather than
skipped — a plan that quietly ignored a file would claim the workspace agrees
with the API about a record it never read.

Add `.minima/` to `.gitignore`; it is a cache, not source.

## Reviewing and applying

A plain `push` prints the plan: what would be created, updated, or left alone.
Read it, then apply:

```sh
minima push --json     # the plan, machine-readable
minima push --apply
```

A failed apply and a clean one both write a report to stdout, with the failures
inside it — they are distinguished by the exit code, so check it in scripts
rather than assuming a written report means success.

## Round-tripping

`pull` keeps its merge baseline under `.minima/`, so a later pull can tell a
local edit from an upstream change and merge instead of overwriting. A key the
server dropped — a cleared attribute — is removed from your file rather than
left behind, so `push` cannot resurrect it later.

Images are pulled and pruned like everything else, but `push` does not plan
them: no operation converges an image file. Upload and publish images with
`minima images upload` and [`minima images publish`](/cli/commands).

Source: https://docs.minima.ltd/cli/workspace/index.mdx