Partiri CLI reference

Overview

The Partiri CLI lets you manage your services directly from the terminal. You can create, deploy, pause, and monitor services — and discover the workspace, project, region, and pod IDs you need — without leaving your development environment. It ships as a single self-contained binary written in Rust, with no system dependencies. Every command accepts the global flags below, so it slots cleanly into shell scripts and CI pipelines.

Installation

Install via Cargo (the Rust package manager):

cargo install partiri-cli

Install via npm:

npm install -g @partiri/cli

Or download a pre-built binary from the Codeberg releases page for Linux and macOS (x64 and arm64), extract it, and add the partiri binary to your PATH.

Authentication

The simplest way to sign in is the browser flow: the CLI opens partiri.cloud, you authenticate, and the resulting API key is written back to your machine. Run:

partiri auth login

For CI pipelines or containers without a browser, set an API key directly. Generate one from your account settings in the dashboard, then pass it on the command line or pipe it through stdin to keep it out of your shell history:

partiri auth set-apikey --key "$PARTIRI_KEY"
echo "$PARTIRI_KEY" | partiri auth set-apikey --key-stdin

Your key is stored at ~/.config/partiri/key with restricted file permissions (mode 0600).

Global flags

These flags work on every command and are designed for scripting and automation:

• --json, -j — Emit machine-readable JSON to stdout (and errors as JSON to stderr). Ideal for piping into jq or driving the CLI from another program.
• --yes, -y — Skip the confirmation prompt on destructive operations such as deploy, kill, and pause.
• --no-input — Never prompt; fail with an error if a required value is missing. Enabled automatically when stdin is not an interactive terminal.

Project setup

Initialize a new project configuration by running partiri init in your project directory. The interactive wizard detects your runtime automatically from files such as package.json, Cargo.toml, requirements.txt, pyproject.toml, go.mod, Gemfile, mix.exs, composer.json, pom.xml, build.gradle, *.csproj, or CMakeLists.txt, and pre-fills the matching build and run commands. It also reads your Git origin remote to fill in the repository URL. The result is a .partiri.jsonc configuration file in JSONC format, which supports comments and trailing commas.

partiri init

Pass partiri init --template to skip the wizard and write a fully commented scaffold instead — useful when you want to fill in the values by hand or in a non-interactive environment.

partiri init --template

Commands

Top-level

• partiri auth login / partiri auth set-apikey — Sign in through the browser, or save an API key directly with --key or --key-stdin.
• partiri init — Interactive setup wizard that creates a .partiri.jsonc config file. Add --template for a non-interactive scaffold.
• partiri validate — Validate your local configuration file. Add --remote to also run live API checks (UUIDs exist, region/pod pairing, repository and registry reachability, health-check probe).

Service

• partiri service create — Register a new service on Partiri and write its ID back to the config.
• partiri service pull — Pull an existing service configuration from Partiri (the only service command that does not need a local config file).
• partiri service list — List the services in a project; useful for discovery without a config file.
• partiri service push — Push local config changes to an existing service.
• partiri service deploy — Trigger a new deployment. Pass --service <UUID> to deploy by ID without a config file.
• partiri service metrics — Show current resource metrics and recent jobs.
• partiri service logs — Show the last 35 log lines from the past hour.
• partiri service jobs — List deployment jobs for the service.
• partiri service pause — Pause the service.
• partiri service unpause — Resume a paused service.
• partiri service kill — Permanently stop and remove the service.
• partiri service link — Set or change the workspace, project, region, pod, and auth-token references in the config.
• partiri service env — Print the service's runtime environment variables, replace them from a .env file with --path, or save them locally with --save. Env vars are never stored in .partiri.jsonc.
• partiri service token — Link or clear an authentication token for private repositories or registries.

Projects and workspaces

• partiri projects list — List all projects in a workspace.
• partiri projects create — Create a new project.
• partiri workspaces list — List all accessible workspaces.

Secrets

• partiri secrets create-registry — Store image-pull credentials for a private container registry.
• partiri secrets create-repository — Store a Git access token for a private repository.
• partiri secrets list — List the registry and repository secrets in a workspace.

Storage

• partiri storage list — List the persistent volumes in a project.
• partiri storage show <UUID> — Show full details for a specific volume.
• partiri storage detach <UUID> — Detach a volume from its service (pause the service first).
• partiri storage delete <UUID> — Delete a volume (it must be detached first).

Discovery

• partiri regions list — List the regions available in a workspace.
• partiri pods list — List the compute pods available in a workspace; add --region to include a monthly price column.

AI agent helpers

The partiri llm family exposes machine-readable helpers for AI agents driving the CLI — guide, schema, template, examples, capabilities, errors, explain, whoami, doctor, context, and next. Pair them with --json for structured output.

MCP server

• partiri mcp install — Install the Partiri MCP server configuration into an AI client.
• partiri mcp uninstall — Remove the Partiri MCP server configuration from an AI client.

Configuration

The CLI uses a .partiri.jsonc file in your project root. This file stores the workspace ID, project ID, and service configuration (runtime, build and run commands, region/pod selection, and an optional persistent disk). After creating a service, its ID is saved to this file automatically. Runtime environment variables are managed separately with partiri service env and are never written to this file.

Environment variables override the defaults: PARTIRI_API_URL sets the API base URL, PARTIRI_WEB_URL sets the partiri.cloud URL the login flow opens (useful for staging), and PARTIRI_TIMEOUT sets the request timeout in seconds (default 30).

.partiri.jsonc reference

The .partiri.jsonc file is created by partiri init and read by all CLI commands. It is a JSONC file — comments (//) and trailing commas are supported. Edit it by hand and push changes with partiri service push.

{
  // The service ID assigned by Partiri after running 'partiri service create'.
  // Leave as null until you have created the service.
  "id": null,

  // The workspace this service belongs to (selected during 'partiri init').
  "workspace": "uuid",

  // The project this service belongs to (selected during 'partiri init').
  "project": "uuid",

  "service": {
    // Display name (max 16 characters), unique within the project.
    "name": "my-api",

    // Service type. Supported values: "webservice" | "static" | "private-service"
    // - webservice:      public HTTP service with an external URL
    // - static:          static file hosting (repository only, registry not supported)
    // - private-service: internal HTTP service, not publicly accessible
    "deploy_type": "webservice",

    // Runtime environment. Supported: "node" | "rust" | "python" | "go" | "ruby"
    //   | "elixir" | "php" | "jvm" | "dotnet" | "cpp" | "static" | "registry"
    "runtime": "node",

    // Path to the root of your application within the repository.
    "root_path": ".",

    // Git repository source.
    "repository_url": "https://github.com/org/repo",
    "repository_branch": "main",
    // Or a registry image source (mutually exclusive with repository_url;
    // not supported for deploy_type "static"). Give the full reference — the
    // API splits host, repository, and tag server-side.
    // "registry_url": "ghcr.io/owner/image:tag",

    // Authentication token for private repository / registry access.
    // "service_secret": "uuid",     // run 'partiri service token' to configure

    // Command to build the project (leave empty if not needed).
    "build_command": "npm run build",
    // "build_path": "dist",            // output directory of the build step
    // "pre_deploy_command": "",        // optional: runs before each deploy (e.g. migrations)

    // Command to start the service at runtime.
    "run_command": "npm start",

    // Region where the service will be deployed.
    "region": "uuid",

    // Compute pod — determines CPU and RAM allocated to the service.
    "pod": "uuid",

    // Health check path (GET). Set to null to disable.
    // "health_check_path": "/health",

    // Enable maintenance mode (serves a maintenance page instead of the app).
    "maintenance_mode": false,

    // Whether the service is active.
    "active": true,

    // Persistent disk (optional). Provisions and attaches a volume on
    // create/push; remove it or set it to null to detach on the next push.
    // Manage volumes with 'partiri storage list/show/detach/delete'.
    // "disk": { "mount_path": "/app/data", "size": 1 }

    // Environment variables are managed with 'partiri service env' and are
    // never stored in this file.
  }
}

Top-level fields:

id

The service ID assigned by Partiri after partiri service create. Null until then — do not set this manually.

workspace

The workspace this service belongs to (selected during partiri init).

project

The project this service belongs to (selected during partiri init).

service object fields:

service.name

Display name for your service on Partiri Cloud. Maximum 16 characters, unique within the project.

service.deploy_type

Service type. One of: webservice (public HTTP service), static (static file hosting, repository only), private-service (internal, not publicly accessible).

service.runtime

Runtime environment. One of: node, rust, python, go, ruby, elixir, php, jvm, dotnet, cpp, static, registry. Use registry when deploying from a container image.

service.root_path

Path to the root of your application within the repository. Use . for the repo root. Set to a subdirectory for monorepos (e.g. apps/api).

service.repository_url

Git repository URL. Mutually exclusive with registry_url. Required for deploy_type static.

service.repository_branch

Branch to deploy. Required when repository_url is set.

service.registry_url

Full container image reference, e.g. ghcr.io/owner/image:tag. Use instead of repository_url when deploying a pre-built image; the API splits the host, repository, and tag. Mutually exclusive with repository_url and not supported for deploy_type static.

service.service_secret

Authentication token for private repository or registry access. Set via partiri service token.

service.build_command

Command to build the project (leave empty if not needed).

service.build_path

Output directory of the build step (e.g. dist). Required for deploy_type static.

service.pre_deploy_command

Runs before each deployment, after the build and before the service starts (e.g. database migrations).

service.run_command

Command to start the service at runtime. Not used for deploy_type static.

service.region

Region where the service will be deployed. List with partiri regions list.

service.pod

Compute pod — determines CPU and RAM allocated to the service. List with partiri pods list.

service.health_check_path

HTTP path the platform polls to verify the service is healthy (e.g. /health). Must return HTTP 200. Set to null to disable.

service.maintenance_mode

When true, serves a maintenance page instead of routing traffic to your application.

service.active

Whether the service is active.

service.disk

Optional persistent volume: { "mount_path": "/app/data", "size": <1–10 GB> }. Setting this provisions and attaches a volume on service create/push; removing it (or setting it to null) detaches on the next push. Manage volumes with partiri storage.

Environment variables are not stored in .partiri.jsonc. Manage them with partiri service env — print them with no arguments, replace them from a dotenv file with --path, or save the service's current values to .env.partiri with --save.