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 version 22 or higher 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] [optional: --partner-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

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.

Claude Code

Add the following to your Claude Code MCP/LSP configuration (typically .claude/settings.json or your global Claude Code settings):

{
  "lsp": {
    "platformos-liquid": {
      "command": ["pos-cli-lsp"],
      "extensions": [".liquid", ".graphql", ".json"]
    }
  }
}

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 — platformOS configuration files

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 app/pos-modules.json, resolves all dependencies, updates app/pos-modules.lock.json, and downloads all module files into the modules/ directory:

pos-cli modules install [module name]
pos-cli deploy <env>

Remove

To remove a module from your application:

pos-cli modules remove [environment] <module name>

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:

   pos-cli modules version x.x.x pos-cli modules push --email <your_email>

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:

• Read our documentation on Migrations
• or follow the step-by-step guide on Migrating Data.

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.

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.

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

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

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.

Starting the MCP Server

pos-cli mcp

This starts both a stdio transport (for editor/AI integrations) and an HTTP/SSE server on port 5910 (configurable with MCP_MIN_PORT).

Configuring Claude Code

Add the following to your Claude Code settings (.claude/settings.json) to use pos-cli as an MCP server:

{
  "mcpServers": {
    "platformos": {
      "command": "pos-cli-mcp"
    }
  }
}

Available Tools

The MCP server exposes 30+ tools across these categories:

• Environments: envs-list, env-add
• Deploy: deploy-start, deploy-status, deploy-wait
• Sync: sync-file
• Logs: logs-fetch
• GraphQL: graphql-exec
• Liquid: liquid-exec
• Data: data-import, data-import-status, data-export, data-export-status, data-clean, data-clean-status, data-validate
• Migrations: migrations-list, migrations-generate, migrations-run
• Tests: unit-tests-run, tests-run-async, tests-run-async-result
• 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

Viewing Tool Configuration

To see which tools are enabled or disabled:

pos-cli mcp-config

Use --json for raw JSON output. You can override the configuration by setting the MCP_TOOLS_CONFIG environment variable to point to a custom tools.config.json file.

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:

{"id":"1001","message":"Hello","type":"debug","created_at":"2026-01-01T12:00:00Z"}
{"id":"1002","message":"World","type":"info","created_at":"2026-01-01T12:00:01Z"}

Each entry contains an id field. Pass the highest id from a previous run to --last-log-id to fetch only newer logs on the next poll:

pos-cli fetch-logs staging --last-log-id 1002

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.