pos-cli is a command-line interface (CLI) tool specifically developed to simplify the deployment of your configuration files and assets to platformOS. It requires a specific file structure to ensure correct communication with the platformOS API. While its use is not mandatory, it is highly recommended. Basic familiarity with command line environments, such as Terminal, is expected when using pos-cli.
If you encounter any issues, have feedback, or want to request new features, please go to our issues page and let us know.
Run all commands from the project root directory, one level above the app or modules directory.
pos-cli requires Node.js 22.22.2 or later on the 22 line, 24.15.0 or later on the 24 line, or 26.0.0 or later, to function correctly. See instructions for installing Node.js on your platform.
If Node.js is installed on your system for all users, you may need to use the sudo command to install npm packages globally:
sudo npm install -g @platformos/pos-cli
If you're using nvm (Node Version Manager) or if Node.js is installed only for your user account, use:
npm install -g @platformos/pos-cli
To authenticate, you'll need your Partner Portal account credentials. If you don't have a Partner, follow the Sign up on the Partner Portal guide.
To add an environment to your configuration file, use the env add command and authenticate with your Partner Portal credentials:
pos-cli env add [environment] --url [your application url] [--partner-portal-url [portal url]]
Examples:
pos-cli env add staging --url https://example.com
pos-cli env add staging --url https://example.com --partner-portal-url https://portal.private-stack.online
--partner-portal-url selects which Partner Portal deployment the CLI authenticates against. It defaults to https://partners.platformos.com, so you only need it when your Instance is managed by a different portal — for example a private stack. The value is saved with the environment as partner_portal_url in the .pos file, so you pass it only when adding the environment: the dns commands read it back per environment, and pos-cli deploy exports it as PARTNER_PORTAL_HOST for the deploy run.
Note that modules install/update take their registry URL from the PARTNER_PORTAL_HOST environment variable (or per-module overrides), not from .pos — so to resolve modules from a non-default portal, set that variable as well.
The Instance details page in the Partner Portal shows the env add command pre-filled with both URLs, ready to copy.
If your Partner Portal account has two-factor authentication enabled, the portal asks for a second factor before issuing a token: the token env add mints is bound to the one Instance you named and stays valid for a year unless revoked in the portal.
Nothing extra is needed for the default flow: pos-cli env add [environment] --url [url] (no --email) authorizes in the browser, where you answer the 2FA challenge like any other portal login.
When you authenticate with --email, pos-cli prompts for the code after your password:
pos-cli env add staging --url https://example.com --email you@example.com
Password: ******
This account has two-factor authentication enabled. Your password was accepted.
Two-factor code (or a recovery code): 123456
A recovery code from the list you saved when you enabled 2FA is accepted anywhere the six-digit code is. To skip the prompt, pass --otp-code or set POS_PORTAL_OTP_CODE:
pos-cli env add staging --url https://example.com --email you@example.com --otp-code 123456
POS_PORTAL_OTP_CODE=123456 pos-cli env refresh-token staging
The same applies to pos-cli env refresh-token and pos-cli modules push. In a non-interactive environment (CI, a --json run) pos-cli will not prompt — supply POS_PORTAL_OTP_CODE, or prefer pos-cli env add [environment] --url [url] --token [token], which needs neither a password nor a code.
An instance can require that it is used with a credential whose holder has proved a second factor — the year-long token in .pos is not one. This covers every command that talks to the instance, not just deploys: deploy, sync, exec, exec-graphql, exec-liquid, constants, data export/import, migrations, logs, pull, the GUI. A token reaches every record in the instance through GraphQL and runs arbitrary Liquid through exec liquid, so reads are not exempt.
The first command that needs one asks for a code:
pos-cli deploy staging
Your Partner Portal account (you@example.com) has 2FA enabled.
Instance: https://example.com
Portal: https://partners.platformos.com
Two-factor code (or a recovery code): 123456
2FA is enabled on your Partner Portal account, not on the Instance — the Instance only insists that the credential it is handed belongs to someone who has proved it. The Instance, portal and account are printed so you can confirm what a code is about to unlock, and which account it should come from, before typing it. The account is the email stored for the environment in .pos; environments added through the browser device flow store none, and that line is left out.
The Partner Portal decides how long the session lasts and pos-cli prints the expiry as it starts one (Two-factor session started — it expires in 59 minutes.). It is cached as two_factor_session inside that environment's entry in .pos, so every later command in that window runs without a prompt — one code unlocks the whole session, whichever command asked for it. Caching a session tightens .pos to owner-only (0600), since it now holds a credential shorter-lived than the year-long token. When settings come from MPKIT_URL/MPKIT_EMAIL/MPKIT_TOKEN there is no .pos entry to write to, and the session is kept only for the life of the process — enough for one long sync, but the next command asks again.
For scripted runs, set POS_PORTAL_OTP_CODE: it works for every command, while the --otp-code flag exists only on deploy, sync, gui serve, env add, env refresh-token and modules push. A recovery code works in either and does not expire on a timer. If your orchestrator already holds a session token, POS_PORTAL_SESSION_TOKEN supplies it directly and skips the exchange entirely; pos-cli only reads that variable, and never writes a session token to its output. deploy, sync and gui serve ask up front, before doing any work; other commands ask at the moment the instance refuses, and then retry the request that was refused. gui serve asks even without --sync, because the GUI proxies every panel query through the same credential. If a session expires part-way through a sync, watch mode stops rather than prompting into a queue that is mid-flight — it reports what did not reach the instance and asks you to restart the command you started, which takes a code once, up front. Under gui serve --sync that stops the web server too: the same session the watcher was refused is one no panel query could have used either.
pos-cli stops after three rejected codes. The Partner Portal locks an account for 15 minutes after five, and that counter is shared with the web UI, so the remaining attempts are left for you to spend deliberately. If the account is already locked, pos-cli says so and stops without asking for a code — while the lock holds, even a correct code is refused unread.
The configuration for your environments is stored in the .pos file.
To synchronize changes with your environment, use the following command:
pos-cli sync [environment]
Example: pos-cli sync staging
Using this command activates sync mode, which immediately uploads any changes you make to your local file system to the specified environment. This offers an experience similar to working on a local server. However, because changes are applied instantly, using sync mode on a production environment or a live application is risky and not recommended. It's best to limit the use of this feature to staging environments where immediate updates can be tested safely.
Include the --open (-o) option with your sync command to automatically launch your Instance in the default web browser:
pos-cli sync [environment] -o
By default, the sync command establishes three concurrent connections to our server for syncing resources and assets. You have the option to modify this to better suit your network's capabilities:
pos-cli sync [environment] -c 10
Adjust the number of concurrent connections based on your specific requirements and connection strength.
To sync a single file without entering watch mode, use the -f or --file-path option:
pos-cli sync [environment] -f path/to/file.liquid
This command syncs only the specified file and exits immediately, making it useful for scripting where you need to update a specific file without keeping a persistent connection.
To deploy all changes to a specified environment, use the following command:
pos-cli deploy [environment]
Example: pos-cli deploy staging
It is recommended to first deploy changes to a staging environment, thoroughly test them there, and only then proceed with deploying to production. The deploy command packages all your files into a zip file and sends it to the API for background processing. Each zip file is stored, enabling rollback if any issues arise.
To skip the audit during deployment, set the environmental variable CI to true.
To validate your release on the server without applying any changes, use the --dry-run flag:
pos-cli deploy [environment] --dry-run
Example: pos-cli deploy staging --dry-run
This uploads the release archive and runs server-side validation but does not apply any changes. The server reports which files would be upserted and which would be deleted, making it useful for previewing the impact of a deployment before committing to it. Assets are never uploaded during a dry run.
To perform a static analysis of the files in your current application directory, use the following command:
pos-cli audit
Example: pos-cli audit
This command checks your application files for issues using static analysis, helping you maintain code quality and identify potential errors.
pos-cli provides a powerful Liquid code quality checker powered by platformos-check. This helps you catch issues early, enforce best practices, and maintain high-quality code.
Before running checks, you can create a .platformos-check.yml configuration file to customize which checks to run:
pos-cli check init [path]
Example: pos-cli check init
This creates a .platformos-check.yml file that:
- Extends the recommended platformos-check configuration
- Ignores
node_modules/**by default - Includes all available settings as comments for easy customization
To check your Liquid code quality, use:
pos-cli check run [path]
Example: pos-cli check run
This command analyzes Liquid templates for common issues, syntax errors, and best practices violations. By default, it checks the current directory, but you can specify a path to check a specific directory.
The output includes:
- Severity levels: Errors, warnings, and info messages color-coded for easy identification
- Code snippets: Shows the actual problematic code with line numbers
- Grouped by file: Offenses are organized by file for better readability
- Summary counts: Total offenses broken down by severity
-a- Enable automatic fixing of issues where possible-c, --check <name>- Only show offenses from the named check (repeatable, e.g.-c UndefinedObject -c UnusedAssign)-f <format>- Output format:text(default) orjson-s, --silent- Only show errors, no success messages
Check current directory:
pos-cli check run
Check specific directory:
pos-cli check run ./app/views
Auto-fix issues:
pos-cli check run -a
JSON output for CI/CD:
pos-cli check run -f json
Silent mode (no success message):
pos-cli check run -s
Filter by specific check:
pos-cli check run --check UndefinedObject
Filter by multiple checks:
pos-cli check run -c UndefinedObject -c UnusedAssign
Combined options:
pos-cli check run -a -f json
The command exits with code 0 if no issues are found, or 1 if issues are detected, making it suitable for CI/CD pipelines.
Text output displays offenses grouped by file with code snippets:
3 offenses found in 1 file:
3 warnings
app/views/pages/index.liquid
[warning] UndefinedObject
Unknown object 'user' used.
5 <p>{{ user.name }}</p>
JSON output provides structured data with severity counts:
{
"offenseCount": 3,
"fileCount": 1,
"errorCount": 0,
"warningCount": 3,
"infoCount": 0,
"files": [
{
"path": "app/views/pages/index.liquid",
"offenses": [...],
"errorCount": 0,
"warningCount": 3,
"infoCount": 0
}
]
}After running pos-cli check init, you can customize .platformos-check.yml:
extends: platformos-check:recommended
ignore:
- node_modules/**
- dist/**
# Customize individual checks
UndefinedObject:
enabled: true
severity: error # error (0), warning (1), or info (2)
DeprecatedFilter:
enabled: true
severity: warningThe configuration file controls:
- Which checks are enabled/disabled
- Severity levels for each check
- File patterns to ignore
- Check-specific settings
To download the latest platformOS Liquid documentation used by the linter:
pos-cli check update-docs
The linter automatically checks whether its cached documentation is stale and updates it when needed. However, if you want to be sure you have the latest platformOS filters, tags, objects, and schema, you can use this command to force a download.
pos-cli includes a Language Server Protocol (LSP) server for platformOS Liquid, enabling rich editor support such as autocompletion, diagnostics, hover documentation, and go-to-definition in any LSP-compatible editor.
The server communicates over stdio (standard input/output), which is the standard LSP transport. You do not start it manually — your editor launches it automatically based on your configuration.
Installing pos-cli globally (npm install -g @platformos/pos-cli) automatically places pos-cli-lsp on your PATH — no wrapper script needed. Configure your editor to use it as the language server.
Add the following to your editor's settings.json (Ctrl+Shift+P → "Open User Settings (JSON)"):
{
"lsp": {
"platformos-liquid": {
"command": ["pos-cli-lsp"],
"extensions": [".liquid", ".graphql", ".json"]
}
}
}The language server provides IDE features for:
.liquid— platformOS Liquid templates.graphql— GraphQL queries and mutations
.json is deliberately not mapped to the language server. It answers nothing for a JSON file, and
claiming the extension would make it the language server for every package.json and tsconfig.json
in the project as well.
Once configured, the language server provides:
- Autocompletion — Liquid tags, filters, and platformOS-specific variables
- Diagnostics — Real-time error and warning highlighting
- Hover documentation — Inline docs for tags and filters
- Go-to-definition — Navigate to template, partial, and schema definitions
Use the logs command to access errors and logs that you or the system logs:
pos-cli logs [environment]
Read more on how to create logs.
Once activated, this command continuously displays logs as long as it is running. If supported by your operating system, errors will also trigger system notifications.
You can filter logs displayed by specifying a type with the --filter argument.
pos-cli logs [environment] --filter type
Example:
pos-cli logs staging --filter debug
This command filters and displays only the logs of type 'debug' from the staging environment.
For more details, read our documentation on logs.
examples:
pos-cli logsv2 search stg --size 5 --from 0
pos-cli logsv2 search stg --sql "select * from logs" --json | jq
pos-cli logsv2 search stg --sql "select message,type from logs" --json | jq
pos-cli logsv2 search stg --sql "select * from logs where str_match(message, 'com')" --start_time 1694694303000000 --size 5 | jq
- alerts
- alerts delete
- better errors
- GUI
If you need to recall the names of your environments or their corresponding URLs, use the following command:
pos-cli env list
To start a new project from scratch and set up the initial directory structure, use the init command:
pos-cli init --url mdyd-dev/directory-structure --branch master
Default URL: mdyd-dev/directory-structure
Default branch: master
The init command uses degit to download the directory structure from the specified Git repository and extract it into your current directory. It supports all file formats that degit can handle, simplifying the setup process for new projects.
Add constant named API_KEY with value abc123 on dev environment:
pos-cli constants set --name API_KEY --value abc123 dev
Remove constant API_KEY on staging environment:
pos-cli constants unset --name API_KEY staging
List defined constants without exposing their values on production environment:
pos-cli constants list production
SECRETTOKEN "XX..."
TEMP_TOKEN "XX..."
USE_SEARCH_INDEX "tr..."
List defined constants showing their values on production environment:
SAFE=1 pos-cli constants list production
SECRETTOKEN "XXXXXXX"
TEMP_TOKEN "XXXXXXXXXXXXXX"
USE_SEARCH_INDEX "true"
Use the following command to display all modules that have been installed through the Partners Portal for a specific environment:
pos-cli modules list [environment]
Note: This command does not list modules that you deployed manually via the modules/ directory. For example, if you create a directory manually, such as modules/my-module, and add a file like modules/my-module/public/views/partials/my-partial.liquid, my-module will not appear in the list produced by this command.
However, if you install a module using the pos-cli modules install another-module command or directly through the "Install" option in the Partners Portal interface, the module will be listed by this command.
To create a new module using a template from a starter repository, use the following command, where <module name> is your desired module name:
pos-cli modules init <module name>
This command sets up a new directory within the modules/ folder, pulling the initial structure and content from the Platform-OS module template repository.
Example of creating a module named "new": ~/projects/pos/modules/pos-module-new pos-cli modules init new [11:02:21] Module directory structure successfully created.
After running the command, you can see the new module directory has been created by listing the contents:
~/projects/pos/modules/pos-module-new ls
modules
~/projects/pos/modules/pos-module-new cd modules
~/projects/pos/modules/pos-module-new/modules ls
new
~/projects/pos/modules/pos-module-new/modules cd new
~/projects/pos/modules/pos-module-new/modules/new ls
CHANGELOG.md changelog-template.hbs LICENSE package.json private public pull_request_template.md README.md template-values.json
Install modules published in the modules marketplace. The install command adds the module to pos-module.json, resolves all transitive dependencies, writes pos-module.lock.json, and downloads all module files into the modules/ directory.
Two files, two purposes:
pos-module.json— your declared intent. Edit this file to express which modules you want and at what version constraints. Commit it to source control.pos-module.lock.json— auto-generated. Records the exact resolved version of every module and its transitive dependencies, plus the registry URL each module was resolved from. Commit this too so teammates and CI get identical installs.
Installing a module
# Install latest stable — stores a caret range (e.g. ^2.0.0) in pos-module.json
pos-cli modules install core
# Install with a caret range — allows any compatible 2.x release
pos-cli modules install core@^2.0.0
# Install with a tilde range — allows patch-level updates only (2.1.x)
pos-cli modules install core@~2.1.0
# Install an exact version — no automatic updates
pos-cli modules install core@2.1.5
# Re-resolve and download everything declared in pos-module.json (e.g. after cloning)
pos-cli modules install
# Add a module to devDependencies instead of dependencies
pos-cli modules install tests --dev
# CI mode — use pos-module.lock.json as-is, no registry resolution. Fails fast if the lock file is missing or stale.
pos-cli modules install --frozen
# CI mode including devDependencies
pos-cli modules install --frozen --dev
Version range syntax
| Syntax | Example | What gets installed |
|---|---|---|
| No version | install core |
Latest stable; stores ^MAJOR.0.0 |
Caret ^ |
^2.0.0 |
Highest 2.x.x release (>=2.0.0 <3.0.0) |
Tilde ~ |
~2.1.0 |
Highest 2.1.x patch release (>=2.1.0 <2.2.0) |
| Exact | 2.1.5 |
Exactly 2.1.5, never updated automatically |
| Greater-or-equal | >=2.0.0 |
Highest stable 2.0.0 or above |
| Range | >=2.0.0 <3.0.0 |
Highest stable within the bounds |
Updating modules
# Re-resolve all modules — range entries re-resolve to latest within their range; exact pins are unchanged
pos-cli modules update
# Update a single module to its latest stable (or latest within its stored range)
pos-cli modules update core
# Change a module's constraint to a new range
pos-cli modules update core@^3.0.0
# Pin a module to a specific version
pos-cli modules update core@3.1.0
# Re-resolve devDependencies along with dependencies
pos-cli modules update --dev
Key difference between install and update:
install corewhencoreis already inpos-module.json→ no-op on the constraint; dependencies are still re-resolved and any missing files downloaded.update corewhencorehas an exact pin → always fetches the latest stable release and updates the pin.update corewhencorehas a range (e.g.^2.0.0) → re-resolves to the latest within that range; the range itself is unchanged inpos-module.json.
After installing or updating, deploy to apply the changes to your instance:
pos-cli deploy <env>
Display all versions of a module published in the registry:
pos-cli modules show <module-name>
Remove a module from your local project. This removes the entry from pos-module.json, re-resolves the dependency tree, updates pos-module.lock.json, and removes the module's files from modules/:
pos-cli modules uninstall <module-name>
# Remove from devDependencies
pos-cli modules uninstall <module-name> --dev
To remove a module from a deployed instance (different from local uninstall):
pos-cli modules remove [environment] <module name>
If your project still uses the legacy app/pos-modules.json (or has metadata fields like machine_name/version inside template-values.json), migrate to the unified pos-module.json:
pos-cli modules migrate
The migration runs two independent, idempotent phases:
- Phase A — converts
app/pos-modules.json→pos-module.json(moduleskey →dependencies). - Phase B — lifts
machine_name,version,name,repository_urlfrommodules/<name>/template-values.jsonintopos-module.jsonand strips them from the source file (deleting the file if it becomes empty).
When multiple modules/<name>/template-values.json files exist, target a specific module:
pos-cli modules migrate --name <machine_name>
By default, install and update resolve modules from the public registry (overridable via PARTNER_PORTAL_HOST). To resolve specific modules from a private or custom registry, declare a registries map in pos-module.json:
{
"name": "My App",
"dependencies": {
"core": "^1.5.0",
"private-module": "^1.0.0"
},
"registries": {
"private-module": "https://portal.private-stack.online"
}
}After each install/update, every resolved module gets its registry URL stamped into pos-module.lock.json, making the lock file self-contained for --frozen mode.
To publish a module to our module repository,
-
Create the module on the Partner Portal and give it a unique name.
-
Create a separate directory for your module and run
pos-cli init <module_name>to create necessary directory structure.mkdir <module_name>; cd <module_name> pos-cli init <module_name>
-
After preparing your module, release the new version and then publish it:
pos-cli modules version patch
pos-cli modules version 1.2.3
pos-cli modules push --email <your_email>
pos-cli modules version updates pos-module.json, syncs the version into modules/<name>/template-values.json (when present), and creates a git commit and tag. The command refuses to run on a dirty working tree; use --no-git to skip the commit and tag.
To package the module into a release archive without uploading (e.g. for inspection or manual publishing):
pos-cli modules build
Fetch the codebase of a module that is deployed on your instance:
pos-cli modules pull <env> <module_name>
This will download and unpack module files into the modules/<module_name> directory.
Templates automate and simplify the configuration process in module management. For example, upon installing a module, it is possible to specify URIs under which pages will be available after the module has been installed. This functionality is supported in both sync and deploy modes.
The templates use ERB/EJS-style markup (<%= =%>). with a simple filter & to unescape user-provided values. By default, all values are escaped.
To specify variable values, place them in the template-values.json within the root module directory. You can also specify the path to this configuration file using the TEMPLATE_VALUES_FILE_PATH variable. For example, by executing TEMPLATE_VALUES_FILE_PATH=templates/values.json pos-cli deploy staging the templates/values.json file will be used as values for templates:
TEMPLATE_VALUES_FILE_PATH=templates/values.json pos-cli deploy staging
Directory structure with template-values.json:
modules
└──admincms
├── template-values.json
├── private
│ └── graphql
│ ├── get_models.graphql
│ └── get_pages.graphql
└── public
└── views
└── pages
└── admin.liquidTemplate Usage Example:
A page with this code
---
slug: <%= &desired_location =%>
---
This is using templates <%= what =%> !An example template-values.json:
{
"desired_location": "index",
"what": "magic"
}Will result during deploy/sync in:
---
slug: index
---
This is using templates magic!Migrations are files that contain executable Liquid code (including GraphQL) code, which you can run across different environments. These files also enable you to keep a record of what scripts have been executed, making it easier to track changes and updates.
This is particularly useful if you want to execute the same code on multiple environments after the code has been deployed, like seeding databases with initial data.
For detailed information:
- Read our documentation on Migrations
- or follow the step-by-step guide on Migrating Data.
List all migrations that have been deployed to the server, along with their current status:
pos-cli migrations list [environment] [name]
To create a new migration, use the generate command with a specified name. A timestamp is automatically prepended to the name to ensure that migrations are executed in the order they were created:
pos-cli migrations generate [environment] [name]
Migrations are executed automatically during deployment.
To execute a migration manually, use the run command. Before running a migration, ensure that the migration file has been synchronized with the intended environment.
The migration is identified by the filename without the extension, or simply by the timestamp.
pos-cli migrations run [environment] [name]
Example:
pos-cli migrations run staging 20190715132951_update_admin_password
This command manually runs a specific migration script that updates an admin password in the staging environment.
The dns commands move an instance's custom domains and DNS records between two Partner Portal deployments (for example from partners.platformos.com to a private-stack portal). They talk to both portals' /api/domains API using the tokens stored in your .pos environments (each environment remembers its own partner_portal_url), so both the source and the target environment must be registered with pos-cli env add — or you can pass --source-*/--target-* flags (-portal-url, -token, -email, -instance-uuid) instead.
Only your own records are migrated: platform-managed DNS (load-balancer targets, SSL validation entries, the www-redirect record) is re-created by the target portal automatically.
Save all domains and DNS records of an instance to a versioned JSON file — a backup/audit artifact that import and compare also accept as input:
pos-cli dns export [environment]
pos-cli dns export [environment] -o backup.json
Export from the source portal, transform, apply to the target portal, and print per-domain cutover instructions (which nameservers or verification records to set where). The source portal is only ever read, and a backup export file is always written before anything is applied:
pos-cli dns migrate [sourceEnv] [targetEnv] --dry-run # review the plan first
pos-cli dns migrate [sourceEnv] [targetEnv]
After the plan is displayed you are asked to confirm before anything is applied — pass --yes to skip the prompt (required in scripts/CI). partners.platformos.com is protected as read-only: it can only ever be a migration source, so an accidental argument swap (migrate target source) fails immediately instead of writing to the legacy production portal.
Domains end up in ownership_verification_pending until you complete the printed cutover steps (repoint nameservers at your registrar for domain-full, or add the verification records and repoint your CNAME/A for domain-external). That state is expected before cutover, not an error.
Useful options: --domain <name> (repeatable) migrates selected domains only; --confirm-destructive is required when an update would delete many records already managed on the target.
Show each provisioned domain's status and any pending cutover steps (in case they were missed after a migrate):
pos-cli dns status [environment]
pos-cli dns status [environment] --domain example.com
Apply a previously exported file to a portal (same transform and safety rules as migrate):
pos-cli dns import [environment] --file backup.json --dry-run
pos-cli dns import [environment] --file backup.json
Verify DNS parity between the two sides — exits non-zero when a domain differs in a way that matters (status, setup type, record intent). Expected cross-stack differences (data centers, nameservers, MX case, TXT chunking, and records whose name one DNS provider stores fully-qualified and another stores short, e.g. SRV records moving from Route53 to Cloudflare) are filtered out; --raw compares byte-for-byte instead:
pos-cli dns compare [sourceEnv] [targetEnv]
pos-cli dns compare [sourceEnv] [targetEnv] --ignore-status # before cutover
pos-cli dns compare --source-file before.json --target-file after.json # offline
If the migration dropped records with --drop-value, pass the same patterns to compare so those records are excluded from the parity check instead of reporting as missing forever.
The intended sequence is: migrate → complete the cutover steps → refresh validation from the target portal → compare comes back clean.
import and migrate: 0 success, 1 apply errors, 2 transform errors, 3 only destructive-blocked domains remain. compare: 0 parity, 1 any CRITICAL or missing domain. Dry-runs exit 0 (or 2 when the plan contains transform errors).
This function allows you to export data from your environment to a specified file in JSON format.
Command:
pos-cli data export staging --path=data.json
For more comprehensive guidance on exporting data using the CLI, REST API, and GraphQL, read our documentation on Data Export.
Use this command to import data from a JSON file that follows the proper data structure into your environment:
pos-cli data import staging --path=data.json
For detailed instructions on importing data with different technologies, read our documentation on Data Import Using CSV format.
This command removes data entries from your Instance without altering the underlying data structure:
pos-cli data clean staging
For example, if your model schema is car and it contains 10 entries, this operation will remove these entries but the car schema itself will remain intact.
This function is particularly useful for clearing data when testing your imports/exports, or for resetting your database to a fresh state between tests.
Important: This operation is irreversible. The pos-cli will request confirmation twice before proceeding to ensure that you do not accidentally remove data.
To start the local HTTP server that hosts the GUI, execute the following command:
pos-cli gui serve [environment]
Example: pos-cli gui serve staging
You can access the platformOS Admin GUI by visiting http://localhost:3333.
If you are working on multiple platformOS environments or projects, you can run several instances simultaneously by setting different port numbers for each instance. This is useful when you need to develop or test multiple environments.
By default, the platformOS Admin GUI runs on http://localhost:3333. To work on multiple environments simultaneously, you can specify different ports using the --port flag. For example, to serve the staging environment on port 3337, use:
pos-cli gui serve staging --port 3337This allows you to access the staging environment at http://localhost:3337, while leaving the default port available for other instances. You can repeat this with other environments by assigning unique port numbers.
If you want to open the platformOS Admin in your browser when the GUI server starts (as soon as gui serve is running), include --open (-o) in your command:
pos-cli gui serve [environment] -o
For routine tasks, you might want both the GUI server (gui serve) and data synchronization (sync) to run simultaneously. You can achieve this with a single command:
pos-cli gui serve [environment] -o --sync
To interact with your instance's database using GraphQL, navigate to the GraphiQL interface at in your web browser:
http://localhost:3333/gui/graphql
The sidebar includes schema documentation for reference.
For experimenting and evaluating Liquid templates directly on your Instance, access the Liquid evaluator page in your browser:
http://localhost:3333/gui/liquid
This interface allows you to test and refine Liquid code within the context of your platformOS environment.
Generators are tools that allow you to quickly create files necessary for your project. You can use generators from platformOS modules or create your own custom generators in any directory.
The tool automatically handles dependency installation - if your generator has a package.json, dependencies will be installed automatically when needed.
For example, the core module includes a command generator for creating command files:
pos-cli generate modules/core/generators/command users/create
The crud generator creates a complete CRUD setup with schema, GraphQL, commands, and optionally views:
pos-cli generate modules/core/generators/crud product name:string price:integer --includeViews
You can create and use generators from any directory in your project:
pos-cli generate my/custom/generator arg1 arg2
Custom generators should:
- Have an
index.jsfile that exports a Yeoman generator class - Optionally include a
package.jsonwith dependencies (will be auto-installed) - Follow the yeoman-generator v7 API
For any generator, you can access help documentation with the --generator-help flag:
pos-cli generate modules/core/generators/command --generator-help
pos-cli generate my/custom/generator --generator-help
This displays available arguments, options, and usage examples for the generator.
Execute Liquid code directly on your instance:
pos-cli exec liquid [environment] [code]
Example:
pos-cli exec liquid staging "{{ 'hello' | upcase }}"
You can also execute Liquid code from a file using the -f flag:
pos-cli exec liquid staging -f path/to/script.liquid
Execute GraphQL queries directly on your instance:
pos-cli exec graphql [environment] [query]
Example:
pos-cli exec graphql staging "{ users(per_page: 5) { results { id email } } }"
You can also execute GraphQL from a file using the -f flag:
pos-cli exec graphql staging -f path/to/query.graphql
Pass GraphQL variables as a JSON object with the -p, --params flag:
pos-cli exec graphql staging 'query q($id: ID) { record(id: $id) { id } }' --params '{"id":"42"}'
The --params flag can be combined with -f to supply variables for a query read from a file:
pos-cli exec graphql staging -f path/to/query.graphql --params '{"id":"42"}'
Note: When executing on production environments (environment name contains "prod" or "production"), you will be prompted for confirmation before execution.
To run tests on your instance, you need to have the tests module installed.
pos-cli test run [environment]
Example:
pos-cli test run staging
This command runs all tests and streams the results in real-time, showing individual test outcomes and a summary at the end.
pos-cli test run [environment] [test-name]
Example:
pos-cli test run staging my_test
pos-cli includes a built-in Model Context Protocol (MCP) server that exposes platformOS operations as tools for AI clients such as Claude, Cursor, and other MCP-compatible assistants. This lets AI agents deploy code, run GraphQL queries, manage data, execute migrations, and more — all directly against your platformOS instances.
The fastest way to connect your AI tool is the one-step wizard:
pos-cli ai init
It asks which AI tool you use and registers the two local platformOS MCP servers — platformos-cli (the pos-cli tools listed below) and platformos-supervisor (Liquid/GraphQL/YAML code validation via validate_code) — in that tool's project-scoped configuration:
| Tool | Project configuration | User configuration | Key |
|---|---|---|---|
| Claude Code | .mcp.json |
~/.claude.json |
mcpServers |
| Cursor | .cursor/mcp.json |
~/.cursor/mcp.json |
mcpServers |
| VS Code | .vscode/mcp.json |
the installed build's User/mcp.json (see below) |
servers |
| opencode | opencode.json |
~/.config/opencode/opencode.json |
mcp.servers |
| pi | .pi/mcp.json |
~/.pi/agent/mcp.json |
mcpServers |
| Codex | .codex/config.toml |
~/.codex/config.toml |
mcp_servers |
| Other | prints the JSON snippet for manual setup | — | — |
Codex is the only one of these whose configuration is TOML. pos-cli appends one table per server rather than reparsing the file, so your comments and formatting are never rewritten. It also reads nothing from .codex/ until the project is marked trusted in your global config, which pos-cli ai init offers to do.
Run it from your project root. Existing configuration files are merged, never overwritten — other MCP servers and unrelated settings are preserved, and re-running the command is a no-op. platformos-cli is registered with --profile dev --no-http (see Choosing Which Tools Are Exposed): the tools a coding agent uses, over stdio only. An entry written by an earlier pos-cli — "command": "pos-cli-mcp" with no arguments, or with --profile dev alone — is upgraded to that; an entry you have changed in any other way is left exactly as it is, and the command tells you so. To skip the prompt (e.g. in scripts), pass the tool directly:
pos-cli ai init --tool claude
After the tool question, pos-cli ai init offers two more servers. These are hosted by platformOS over HTTPS, and unlike the two above they run nothing on your machine and take no credentials:
| Server | What it answers |
|---|---|
platformos-liquid |
platformOS Liquid reference — tags, filters, objects, and language rules, from the official documentation |
platformos-graphql |
the platformOS GraphQL schema — 200+ operations and types, with worked examples |
They are reference only: looking something up is all they do, and they point back at platformos-cli (liquid-exec, graphql-exec, check-run) to actually run it. Their value is that platformOS Liquid is not Shopify Liquid — an agent that guesses a tag or a field name writes code that looks right and is not, and these are what stop the guessing.
Because the answers are the same for every project, the prompt asks where to register them:
? Also register the platformOS documentation servers (Liquid and GraphQL reference)?
> Yes, for this project
Yes, for all my projects
No
"Yes, for all my projects" writes them to your user configuration instead, so they are available everywhere and stay out of a project file you commit. VS Code is the exception: its user configuration lives in a per-build directory (Code, Code - Insiders, VSCodium), so pos-cli looks for one that exists under your platform's user-data path and writes there. If it finds none it prints the snippet and asks you to run VS Code's own MCP: Open User Configuration command, rather than writing a file no installed build would read.
--tool takes the defaults without asking, and the default here is yes, into the project configuration. Use --docs to say otherwise:
pos-cli ai init --tool claude # local servers + documentation servers, in the project
pos-cli ai init --tool opencode --docs global # documentation servers in ~/.config/opencode/opencode.json
pos-cli ai init --tool claude --no-docs # local servers only, as before 6.7
If you script pos-cli ai init --tool <tool> and want it to keep writing only the two local servers, add --no-docs.
The server used to be called platformos and is now platformos-cli, after the command it runs — the old name said nothing about what it was, and the supervisor is platformOS too. pos-cli ai init renames an entry it wrote, in place, and removes the old one so the server is not registered twice. An entry you have customised is left under the old name, with a message saying what the new one would be: rename it yourself, or keep it — nothing breaks either way, since the name is only how your AI tool refers to the server.
Every tool but VS Code adds one more optional step: installing the platformOS Agent Playbook into a directory in your project. The Playbook is platformOS rules, knowledge files, a coding-agent definition and a diagnostics hook — the platform behaviour that fails silently and that no linter catches, written for an agent to read.
There is one archive per tool, because the layout belongs to the tool. They all carry the same platformOS knowledge, compiled from the same source:
| Tool | Installs into | Archive |
|---|---|---|
| Claude Code | .claude/ |
platformos-agent-playbook.zip |
| Cursor | .cursor/ |
platformos-agent-playbook-cursor.zip |
| opencode | .opencode/ |
platformos-agent-playbook-opencode.zip |
| pi | .pi/ |
platformos-agent-playbook-pi.zip |
| Codex | .codex/ |
platformos-agent-playbook-codex.zip |
| Other | platformos-playbook/ |
platformos-agent-playbook-portable.zip |
They are all published under https://documentation.platformos.com/assets/, together with platformos-agent-playbook-checksums.json, the SHA-256 of each archive.
Those fixed URLs can be answered from the CDN's cache long after a new Playbook is deployed, so pos-cli first reads https://documentation.platformos.com/agent-playbook.json. That page is not cached, and it links each archive and the checksum file with the deploy's cache-busting parameter. pos-cli downloads the archive from that link and refuses it if its SHA-256 does not match the checksum file. When the page cannot be read, pos-cli downloads the fixed URL without a checksum, as earlier versions did; set DEBUG=1 to see why.
What differs is the wiring, because the tools provide different mechanisms:
- Claude Code reads per-directory rules natively: a rule file carrying a
paths:field loads only when you open a file it matches, and aPostToolUsehook attaches the documented platformOS claim to a validation finding. - Cursor also reads them natively: a
.cursor/rules/*.mdcfile carrying aglobs:field is attached when a matching file is in context. It has no project-level default agent, so the coding agent's instructions ship as an always-applied rule instead, and no diagnostics hook — Cursor's hook mechanism is not documented. - opencode and pi have neither, so their archives ship a small plugin that reimplements both on the tool's own hooks — it watches which file each tool call touched, delivers the matching rule once per session, and explains a
validate_codefinding from the same table. Both plugins share one delivery module, so they cannot drift apart. - Codex has no lazy per-directory mechanism at all: it builds its instruction chain once at startup from the project root down to the working directory, and a nested
AGENTS.mdis read only when Codex is started in that directory. Its rules therefore ship as files, with an index inAGENTS.mdtelling the agent which one to read before working in a given directory. - Other gets the portable archive, which assumes no mechanism whatsoever. It unpacks to
platformos-playbook/— a directory of its own, so nothing of yours is overwritten — and itsREADME.mdsays how to point your tool at it. Wiring it up is manual, which is the honest position for a tool pos-cli knows nothing about.
VS Code gets no Playbook. Copilot does have native path-scoped instructions, but VS Code runs two agent harnesses with different support for them, so there is no one layout that works.
pos-cli ai init --tool claude --agent-playbook # install it without being asked
pos-cli ai init --tool cursor --agent-playbook
pos-cli ai init --tool opencode --agent-playbook
pos-cli ai init --tool pi --agent-playbook
pos-cli ai init --tool codex --agent-playbook
pos-cli ai init --tool other --agent-playbook # the portable archive
pos-cli ai init --tool claude --no-agent-playbook # never install it, never ask
With neither flag, the question is asked only when the run is interactive. Naming --tool means "do not ask me", so a scripted run installs the Playbook only if it also passes --agent-playbook.
Two things it will not do:
- It never overwrites an existing Playbook directory, or an existing
AGENTS.md. Those hold your own rules and settings, and merging into them would replace them. pos-cli says so and prints the download link so you can unpack and merge by hand. - It never fails
ai init. Every error in this step is caught and reported, and the MCP servers are registered regardless.
Every entry in the archive is checked before anything is written: a path that is absolute, that carries a Windows drive, or that climbs out of the one directory the archive is allowed to write rejects the whole archive. The paths inside the archive's manifest are held to the same rule.
The MCP servers are registered first, so a slow download or a Ctrl-C in the optional Playbook step cannot cost them. Cursor, pi and Codex keep their MCP configuration inside the directory the Playbook unpacks to (.cursor/mcp.json, .pi/mcp.json, .codex/config.toml), so a directory holding nothing but that file is recognised as pos-cli's own: the Playbook is installed around it, and the configuration is kept as it is. A directory holding anything else is yours, and is left alone.
A Playbook that is already in place is still wired on every run (unless you pass --no-agent-playbook): its instruction files are registered in opencode.json, and Codex's AGENTS.md is copied to the project root if there is none. So a run that stopped after unpacking — at an opencode.json that would not parse, or at a Ctrl-C — is finished by running pos-cli ai init again.
opencode's two major versions keep MCP servers in different places, and its published schema still accepts both: opencode 1 puts each server directly under mcp, opencode 2 puts them under mcp.servers and marks the older shape deprecated.
pos-cli follows the format your file already uses. A project with no opencode.json yet takes the format of your global opencode configuration, since the opencode you run wrote that one. When neither says anything, an interactive run asks and a scripted run writes the current format. Either way you can say so outright:
pos-cli ai init --tool opencode --opencode-config v2 # servers under mcp.servers
pos-cli ai init --tool opencode --opencode-config v1 # servers directly under mcp
When pos-cli writes the newer format and finds servers it had previously written under the old key, it moves them rather than adding a second copy — two entries for one server start it twice, and the agent then sees every tool twice. An entry you have customised is left where it is and reported, so you can merge it yourself.
Codex is the one tool here whose configuration is TOML, not JSON. pos-cli reads your file with a TOML parser but never re-emits it: it appends [mcp_servers.<name>] tables, which is sound because TOML tables are order-independent, so your comments and formatting are never rewritten. Every append is checked by parsing the result, and nothing is written unless it means exactly what was intended. An entry already equal to pos-cli's is left in silence; any other entry of that name is yours, is left alone, and is reported with the table pos-cli would have written — the other servers are still added.
More importantly: Codex ignores a project .codex/config.toml entirely until the project is listed as trusted in your global configuration. Measured against codex-cli 0.166.0 — with the project untrusted, codex mcp list reports no servers at all.
[projects."/absolute/path/to/project"]
trust_level = "trusted"
That line lives in ~/.codex/config.toml (or $CODEX_HOME/config.toml). pos-cli will add it for you, but only after asking, because the same flag also allows that project's hooks to run — which is not a decision a setup command should make on your behalf. Decline and it prints the exact block to paste.
pos-cli ai init --tool codex --codex-trust # add the trust block without being asked
pos-cli ai init --tool codex --no-codex-trust # never add it, never ask
Codex also reads instructions only from AGENTS.md in the project root, so the Playbook's AGENTS.md is copied there when you do not already have one. If you do, it is left untouched and the Playbook's copy is named so you can merge from it.
pi ignores everything in .pi/ — the MCP servers, the Playbook, the extension — until the project is trusted. pos-cli reports this after installing, because an untrusted project reads none of it and nothing about the install looks wrong. Start pi in the project and accept its prompt, or set "defaultProjectTrust": "always" in your pi settings.
pos-cli-mcp
pos-cli mcp starts the same server. MCP client configurations should use pos-cli-mcp, which skips the pos-cli launcher process. Without a global install, use:
npx -y -p @platformos/pos-cli pos-cli-mcp
That form works with every published version. The shorter npx -y @platformos/pos-cli mcp needs a release newer than 6.5.0: earlier releases never registered the mcp command, so it fails with unknown command 'mcp'.
This starts both a stdio transport (for editor/AI integrations) and an HTTP server on 127.0.0.1:5910 (port configurable with MCP_MIN_PORT), which serves MCP at /mcp. Pass --no-http for stdio only — what pos-cli ai init writes, since stdio clients never use the listener:
pos-cli-mcp --no-http
The server speaks MCP 2026-07-28 and the 2025 revisions (2025-11-25, 2025-06-18, 2024-11-05), and answers each client in its own revision — a client that opens with server/discover gets the new one, a client that opens with initialize gets the version it asks for. The protocol layer is the MCP TypeScript SDK v2.
A call that fails comes back as a tool result marked isError, carrying a code and message the model can act on, rather than as a protocol error: INVALID_PARAMS for arguments that do not match the tool's schema, the tool's own code when it reports a failure, and INTERNAL_ERROR when it throws. A tool that does not exist, or is not exposed, is still a protocol error.
Tools that only read — envs-list, logs-fetch, job-status, the Partner Portal lookups — are marked readOnlyHint, which some clients use to run them without asking.
The server runs for as long as its MCP client keeps stdin open. When the client closes stdin — which is how MCP clients stop the servers they start — the server stops taking new work, lets calls already running finish (at most 120 seconds, which covers the asset upload deploy-start continues in the background), and exits, releasing its HTTP port. To run the HTTP transport on its own, give it stdin from /dev/null (NUL on Windows):
pos-cli-mcp </dev/null
Every tool definition the server exposes is sent to the AI model with each request, so a smaller set leaves more room for your code. Three options choose the set when the server starts:
pos-cli-mcp --profile dev
pos-cli-mcp --profile dev --include-tools data-import,data-validate
pos-cli-mcp --profile none --include-tools graphql-exec,liquid-exec
pos-cli-mcp --exclude-tools data-clean,constants-unset
--profile <name>— the starting set:full— every tool. The default.dev— what a coding agent uses to edit, check, deploy and verify:check-run,logs-fetch,liquid-exec,graphql-exec,envs-list,deploy-dry-run,deploy-start,job-status,unit-tests-run. Its definitions are about a third of the size offull's.none— no tools; name them with--include-tools.
--include-tools <names>adds tools to the profile. This is not an allowlist, unlike Gemini CLI'sincludeToolssetting; for an allowlist, use--profile none --include-tools ….--exclude-tools <names>removes tools.
Names are comma-separated, and each option can be repeated. Tools disabled in the tool configuration (see Viewing Tool Configuration) stay hidden. The selection is fixed for the life of the process and is the same on both transports for every client, and a tool that is not exposed cannot be called either.
The server refuses to start — with a message, before either transport opens — when a selection is not exactly what it looks like: an unknown profile or tool name, the same tool in both lists, --include-tools naming a tool the tool configuration disables, or a selection that leaves no tools. Any argument other than these three, --no-http, --help and --version is refused too, including pos-cli mcp config; the tool configuration is shown by pos-cli mcp-config.
pos-cli-mcp with no options exposes every tool, as before; the default is planned to become dev in the next major release. pos-cli ai init writes --profile dev --no-http. A project configuration that passes these options to pos-cli 6.5.1 or earlier gets the full set, and an HTTP listener, there: those releases ignore their arguments.
The HTTP server has no authentication: anything that can send it a request can run every enabled tool with the platformOS credentials the server resolves (.pos, MPKIT_*). It is therefore reachable from this machine only, and answers 403 to any request whose Host — or Origin, when present — does not name localhost, 127.0.0.1 or [::1], which keeps web pages from driving it. Two environment variables widen this, deliberately:
MCP_MIN_HOST— bind address (an IP address orlocalhost). A non-loopback value such as0.0.0.0exposes every enabled tool, unauthenticated, to anyone who can reach the port; the server logs a warning on every start in that mode.MCP_MIN_ALLOWED_HOSTS— comma-separated hostnames or IP addresses (no scheme or port, IPv6 in brackets) to accept inHost/Originbesides the loopback names.
A malformed value stops the server at startup. If the port is taken, the server logs HTTP transport not started and stdio keeps working. MCP servers started by pos-cli 6.5.0 or earlier listen on all interfaces without these checks and keep the port until stopped, so restart your MCP clients after upgrading.
| Endpoint | Status |
|---|---|
POST /mcp |
MCP Streamable HTTP. 2026-07-28, and 2025-era clients served statelessly (GET and DELETE answer 405: there is no session to resume). |
GET /health |
{"status":"ok"}, for checking the listener is up without speaking the protocol. |
The pre-SDK HTTP API — GET /, GET /tools, POST /call, POST /call-stream — was removed in 6.6.0. /mcp replaces all of it.
Invoking a tool over stdio by naming it as the JSON-RPC method ({"method":"envs-list"}) has been removed; it was never part of MCP. Use tools/call.
Run pos-cli ai init --tool claude to generate this automatically, or add the following to a .mcp.json file at your project root:
{
"mcpServers": {
"platformos-cli": {
"command": "pos-cli-mcp",
"args": ["--profile", "dev", "--no-http"]
},
"platformos-supervisor": {
"command": "pos-cli-supervisor"
}
}
}Both commands are installed globally with pos-cli (npm install -g @platformos/pos-cli).
pos-cli-supervisor [--project <dir>]
Starts the platformOS MCP supervisor — a stdio-only MCP server exposing a single validate_code tool that lets AI agents validate platformOS Liquid, GraphQL, and YAML files before writing them. It returns structured errors, warnings, proposed fixes, and a must_fix_before_write gate.
The project directory is resolved from --project, then the POS_SUPERVISOR_PROJECT_DIR environment variable, then the current working directory (which is what MCP clients use when launched via pos-cli ai init). All logging goes to stderr — stdout is reserved for the MCP protocol.
The MCP server has 30+ tools across these categories; --profile dev exposes the ones listed under Choosing Which Tools Are Exposed:
- Environments:
envs-list,env-add - Jobs:
job-status - Deploy:
deploy-dry-run,deploy-start - Sync:
sync-file - Logs:
logs-fetch - GraphQL:
graphql-exec - Liquid:
liquid-exec - Data:
data-import,data-export,data-clean,data-validate - Migrations:
migrations-list,migrations-generate,migrations-run - Tests:
unit-tests-run - Constants:
constants-list,constants-set,constants-unset - Generators:
generators-list,generators-help,generators-run - Code quality:
check-run - Uploads:
uploads-push - Partner Portal:
instance-create,partners-list,partner-get,endpoints-list
Four tools start work that outlives the call: deploy-start, data-import, data-export and data-clean. Each returns a job_id alongside its own fields, and job-status reads it back:
job-status { "job_id": "pjob1_…" }
job-status { "job_id": "pjob1_…", "wait_ms": 30000 }
stateisrunning,completedorfailed.completedmeans the operation finished — a test run whose assertions failed iscompleted, because the run did its work;failedmeans the operation itself failed.doneisstate != running.wait_ms(up to 120,000) polls until the job is done or that long has passed, whichever comes first. Hitting the deadline returns the current state withdone: false, not an error.- A deploy that uploaded assets is not
completeduntil those assets are on the CDN, not merely when its release is imported.result.assets.phasesays where they are:uploading(still going up from this machine),processing(the instance is unpacking them),done,failed,none(the deploy had no assets), orunknown— the honest answer when the server that started the upload is no longer running and the instance reports nothing about assets. - The
job_idis opaque: pass it back unchanged. It names the instance the job was started on, so polling with noenvcannot ask a different instance about the same numeric id. If the resolved credentials point elsewhere,job-statususes the.posenvironment that does point at that instance, or refuses — without making a request. Nothing in ajob_idchooses credentials or the host a request goes to.
The server writes to stderr and to ~/.pos-cli/logs/mcp-min.log (MCP_MIN_LOG_FILE moves it), and DEBUG=1 (or MCP_MIN_DEBUG=1) adds request, parameter and protocol detail. Credentials are redacted before anything is written: credential headers, passwords, session ids and device codes are replaced entirely, API tokens are masked to abc...xyz, and Token … / Bearer … values and sensitive URL query parameters are removed from message text. The file is created owner-only (0600), and one written by an earlier release is tightened the next time the server starts.
A log file from pos-cli 6.5.1 or earlier can contain credentials verbatim — Authorization headers, and the API token passed to env-add. Delete ~/.pos-cli/logs/mcp-min.log after upgrading, and rotate any token it recorded.
To see which tools the server exposes, and why each of the others is not exposed:
pos-cli mcp-config
pos-cli mcp-config --profile dev --exclude-tools deploy-start
It takes the same --profile, --include-tools and --exclude-tools options as the server, reports exactly what the server would expose with them, and refuses the same mistakes with the same messages. --json prints that report as JSON — config, profile, include, exclude, exposed and hidden (each with a reason: profile, excluded or disabled); it used to print the raw configuration file.
Each tool's description lives with the tool in mcp-min/. The tool configuration (mcp-min/tools.config.json) can disable a tool or replace its description, and ships doing neither. To use your own, point the MCP_TOOLS_CONFIG environment variable at a tools.config.json. A file that does not match the schema, or names a tool that does not exist, stops the server at startup. A file that is missing or not valid JSON applies nothing: the server logs a warning, and pos-cli mcp-config shows which it was.
For scripting and CI pipelines that need logs in a structured format, use fetch-logs:
pos-cli fetch-logs [environment]
This outputs logs as newline-delimited JSON (NDJSON), one log entry per line, oldest first:
{"id":"1790097410.8077228","message":"probe: boom page reached","error_type":"probe_marker","created_at":"2026-09-22T17:16:50.807Z"}
{"id":"1790097411.2168736","message":"Liquid error (views/pages/boom.liquid:4)","error_type":"Liquid error","created_at":"2026-09-22T17:16:51.216Z"}Each entry contains an id: a microsecond epoch of the same instant created_at names. Pass the
last one back to --last-log-id to fetch only newer entries on the next poll:
pos-cli fetch-logs staging --last-log-id 1790097411.2168736
Pass the id back exactly as it was printed. It is a decimal string, not an integer — the
server treats it as a strict greater-than, so rounding it re-delivers every entry from that
instant and truncating it to whole seconds re-delivers the whole second.
Other options:
| Option | Effect |
|---|---|
-q, --quiet |
Suppress everything on stderr — errors and warnings. The NDJSON on stdout is unaffected. |
--endpoint <url> |
Send the request to this API base URL instead of the environment's. Your stored instance token is sent to the URL you name, so only point it at a host you trust; the command prints where it is sending it. To use a different instance's credentials instead, set MPKIT_URL, MPKIT_EMAIL and MPKIT_TOKEN, or name another environment. |
The command exits when the instance returns no entries newer than the cursor. If it answers with
entries but none newer — which means paging cannot continue — the output so far is valid but
incomplete, and a Stopped early at <id> line is written to stderr.
The pos-cli gui serve command uses a distinct build process for the GraphiQL interface located in the gui/editor/graphql directory.
To prepare for development, you first need to install all necessary dependencies:
npm ci
Then, you can start the development environment by executing:
npm start
Once your development work is done, the next step is to build the production assets to ensure everything is optimized for deployment:
npm run build
After building the production assets, make sure to commit your changes to the repository.

