Skip to content
Platform-OSPublic

About

CLI for platformOS

Resources

Contributing

Stars

16 stars

Watchers

14 watching

Forks

Latest commit

 

History

1,709 Commits

Folders and files

Repository files navigation

Overview

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.

Requirements

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.

Installation and Update

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

Usage

Adding Environments and Authenticating

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.

Two-Factor Authentication

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.

Instance Sessions

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.

Syncing Changes

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.

Automatically Opening the Browser

Include the --open (-o) option with your sync command to automatically launch your Instance in the default web browser:

pos-cli sync [environment] -o

Concurrency

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.

Syncing a Single File

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.

Deploying Changes

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.

Dry Run

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.

Code Audit

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.

Liquid Code Quality Check

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.

Initialize Configuration

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

Run Checks

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

Options

  • -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) or json
  • -s, --silent - Only show errors, no success messages

Examples

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.

Output Format

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
    }
  ]
}

Configuration File

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: warning

The configuration file controls:

  • Which checks are enabled/disabled
  • Severity levels for each check
  • File patterns to ignore
  • Check-specific settings

Update Docs

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.

Language Server Protocol (LSP)

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.

Configure Your Editor

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.

Open Code (open-vsx / VSCodium-compatible editors)

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"]
    }
  }
}

Supported File Types

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.

Features

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

Reading Logs

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.

Logs V2

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

ROADMAP

  • alerts
  • alerts delete
  • better errors
  • GUI

Listing environments

If you need to recall the names of your environments or their corresponding URLs, use the following command:

pos-cli env list

Initializing the directory structure

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.

Managing Constants

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"

Modules

List

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.

Initialiting a New Module

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

Installation

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 core when core is already in pos-module.json → no-op on the constraint; dependencies are still re-resolved and any missing files downloaded.
  • update core when core has an exact pin → always fetches the latest stable release and updates the pin.
  • update core when core has a range (e.g. ^2.0.0) → re-resolves to the latest within that range; the range itself is unchanged in pos-module.json.

After installing or updating, deploy to apply the changes to your instance:

pos-cli deploy <env>

Show available versions

Display all versions of a module published in the registry:

pos-cli modules show <module-name>

Uninstall

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>

Migrate to the new manifest format

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 (modules key → dependencies).
  • Phase B — lifts machine_name, version, name, repository_url from modules/<name>/template-values.json into pos-module.json and 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>

Per-module registry overrides

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.

Publishing

To publish a module to our module repository,

  1. Create the module on the Partner Portal and give it a unique name.

  2. 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>

  3. After preparing your module, release the new version and then publish it:

    Bump using a semver type (major | minor | patch). Defaults to patch when no argument is given.

    pos-cli modules version patch

    …or set an explicit version

    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

Pulling module codebase

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.

Module Templates

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.liquid

Template 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

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:

List

List all migrations that have been deployed to the server, along with their current status:

pos-cli migrations list [environment] [name]

Generate

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.

Run

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.

DNS (migrating domains between Partner Portals)

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.

Export

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

Migrate

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.

Status

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

Import

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

Compare

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.

Exit codes

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).

Data

Export

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.

Import

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.

Clean Data (Staging Only)

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.

Admin - Graphical Interface (GUI)

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.

Screenshot of the Admin GUI

Working with Multiple Local Instances

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 3337

This 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.

Opening Admin Automatically

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

Syncing with GUI

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

Exploring with GraphiQL Browser

To interact with your instance's database using GraphQL, navigate to the GraphiQL interface at in your web browser:

http://localhost:3333/gui/graphql

Screenshot of the GraphiQL Browser

The sidebar includes schema documentation for reference.

Liquid Evaluator

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

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.

Using Module Generators

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

Using Custom Generators

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.js file that exports a Yeoman generator class
  • Optionally include a package.json with dependencies (will be auto-installed)
  • Follow the yeoman-generator v7 API

Generator Help

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.

Executing Code

Execute Liquid

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

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.

Running Tests

To run tests on your instance, you need to have the tests module installed.

Run All Tests

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.

Run a Single Test

pos-cli test run [environment] [test-name]

Example:

pos-cli test run staging my_test

MCP Server (AI Integration)

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.

Quick setup: pos-cli ai init

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
The documentation servers

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.

The platformOS Agent Playbook

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 a PostToolUse hook attaches the documented platformOS claim to a validation finding.
  • Cursor also reads them natively: a .cursor/rules/*.mdc file carrying a globs: 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_code finding 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.md is read only when Codex is started in that directory. Its rules therefore ship as files, with an index in AGENTS.md telling 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 its README.md says 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 configuration formats

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: TOML, and the project trust flag

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: project trust

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.

Starting the MCP Server

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

Protocol Revisions

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

Choosing Which Tools Are Exposed

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 of full'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's includeTools setting; 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 or localhost). A non-loopback value such as 0.0.0.0 exposes 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 in Host/Origin besides 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.

HTTP Endpoints

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.

Configuring Claude Code

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).

Supervisor MCP server (pos-cli-supervisor)

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.

Available Tools

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

Asynchronous Operations

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 }
  • state is running, completed or failed. completed means the operation finished — a test run whose assertions failed is completed, because the run did its work; failed means the operation itself failed. done is state != 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 with done: false, not an error.
  • A deploy that uploaded assets is not completed until those assets are on the CDN, not merely when its release is imported. result.assets.phase says where they are: uploading (still going up from this machine), processing (the instance is unpacking them), done, failed, none (the deploy had no assets), or unknown — the honest answer when the server that started the upload is no longer running and the instance reports nothing about assets.
  • The job_id is opaque: pass it back unchanged. It names the instance the job was started on, so polling with no env cannot ask a different instance about the same numeric id. If the resolved credentials point elsewhere, job-status uses the .pos environment that does point at that instance, or refuses — without making a request. Nothing in a job_id chooses credentials or the host a request goes to.

Logs and Debugging

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.

Viewing Tool Configuration

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.

Fetching Logs (Machine-Readable)

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.

Development

The pos-cli gui serve command uses a distinct build process for the GraphiQL interface located in the gui/editor/graphql directory.

Setting Up Development Environment

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

Building and Committing Changes

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.

About

CLI for platformOS

Resources

Contributing

Stars

16 stars

Watchers

14 watching

Forks

Releases

Packages

Used by

Contributors

Languages