JourneyApps Platform CLI

jp is the primary binary for the JourneyApps Platform CLI.

This npm package publishes a fully bundled and minified Node CLI. End users only need Node installed; they do not need pnpm, the monorepo, or any internal workspace packages at runtime.

The shipped binaries are:

• jp
• journeyapps-platform

jp is the primary command name. We are intentionally avoiding journey because it conflicts with an existing internal CLI.

Contents

• Getting Started
• Current Command Surface
• Input
• Output
• FAQ
• Examples

Getting Started

Create a personal access token in Oxide from the token management flow. Inside the Oxide codebase this is implemented in the Cardinal token module, so the UI wording to look for is "token" or "personal access token".

Export it in your shell:

export JOURNEYAPPS_PLATFORM_TOKEN=...

You can also place it in a local .env file:

JOURNEYAPPS_PLATFORM_TOKEN=...

Test access by listing visible projects:

jp projects list --output "table"

Current Command Surface

The currently shipped commands are the real implemented commands:

• jp meta capabilities
• jp ai install-skill
• jp projects list
• jp projects inspect
• jp source pull
• jp source diff
• jp source drafts list
• jp source drafts pull
• jp source drafts diff
• jp source drafts push
• jp deployments list
• jp deployments inspect
• jp deployments create
• jp deployments deploy
• jp deployments logs
• jp deployments logs inspect
• jp deployments logs operation

Input

The CLI accepts input from a few layers:

• CLI flags for explicit one-off control
• environment variables for CI and local shells
• .env files for project-local defaults
• .journey.yml for checked-in structured config

For identifiers, prefer explicit flags like --project-id, --project-name, --deployment-id, and --deployment-label.

The CLI resolves values in this order:

1. CLI flags
2. Process environment
3. .env
4. .journey.yml
5. Param defaults

Environment variables use the JOURNEYAPPS_PLATFORM_* prefix, for example:

JOURNEYAPPS_PLATFORM_TOKEN=...
JOURNEYAPPS_PLATFORM_PROJECT=my-project
JOURNEYAPPS_PLATFORM_DEPLOYMENT=my-deployment
JOURNEYAPPS_PLATFORM_STAGING=true

YAML configuration is namespaced under journeyapps.platform:

journeyapps:
  platform:
    project: my-project
    deployServiceUrl: https://deploy.journeyapps.com

Output

The CLI supports a few output modes depending on whether the caller is a human, CI, or an AI agent.

• json: compact machine-safe JSON
• json-pretty: human-friendly JSON formatting
• yaml: structured human-readable output
• csv: list output for spreadsheets and scripts
• table: list output for the terminal

Tiny examples:

json

{"id":"app_123","name":"my-project","locked":false}

json-pretty

{
  "id": "app_123",
  "name": "my-project",
  "locked": false
}

yaml

id: app_123
name: my-project
locked: false

csv

id,name,locked
app_123,my-project,false

table

| id      | name       | locked |
|---------|------------|--------|
| app_123 | my-project | false  |

Use --output-fields to reduce table and CSV output to a small set of useful columns, or --output-fields-all to include every field.

FAQ

How do I see all commands?

jp meta capabilities --output "table"

How do I get the same catalog for AI or tooling?

jp meta capabilities --output "json"

Examples

List visible projects:

jp projects list --output "table"

List supported commands and parameters:

jp meta capabilities --output "json"

Install the bundled Journey helper into Codex:

jp ai install-skill

Install the bundled Journey helper into Claude Code:

jp ai install-skill --assistant claude

List the same command catalog in a human-readable format:

jp meta capabilities --output "table"

Inspect a project with machine-safe output:

jp projects inspect --project-name "my-project" --output "json"

Pull source for a project branch into a local directory:

jp source pull \
  --project-name "my-project" \
  --branch "master" \
  --dir "./app" \
  --output "json"

See the local source diff against the platform branch:

jp source diff \
  --project-name "my-project" \
  --branch "master" \
  --dir "./app" \
  --output "table"

Pull source from an Oxide-visible draft into a local directory:

jp source drafts pull \
  --project-name "my-project" \
  --draft-id "draft_id" \
  --dir "./app" \
  --output "json"

See the local diff against a draft:

jp source drafts diff \
  --project-name "my-project" \
  --draft-id "draft_id" \
  --dir "./app" \
  --output "table"

Push local source changes into a draft without committing:

jp source drafts push \
  --project-name "my-project" \
  --draft-id "draft_id" \
  --dir "./app" \
  --output "json"

List drafts for a project:

jp source drafts list --project-name "my-project" --output "table"

Inspect a deployment with human-friendly output:

jp deployments inspect \
  --project-name "my-project" \
  --deployment-label "testing" \
  --output "json-pretty" \
  --colors

Use checked-in or local config without repeating project flags:

jp projects inspect --output "json"

List deployments as a table with a small column set:

jp deployments list \
  --project-name "my-project" \
  --output "table" \
  --output-fields "label,region_environment,managed,last_deployed_time" \
  --colors

Create a staging deployment:

jp deployments create \
  --project-name "my-project" \
  --name "Staging Deployment" \
  --environment "staging"

Deploy a branch and wait for completion:

jp deployments deploy \
  --project-name "my-project" \
  --deployment-label "testing" \
  --branch "main" \
  --wait \
  --output "json"

Inspect a single deploy log:

jp deployments logs inspect \
  --reference-id "deploy_log_reference_id" \
  --output "json-pretty" \
  --colors

Fetch operation logs for a deploy:

jp deployments logs operation \
  --reference-id "deploy_log_reference_id" \
  --operation "BACKEND" \
  --output "table" \
  --colors

Use staging defaults without manually specifying service endpoints:

jp --staging deployments list --project-name "my-project"

Use an explicit config file:

jp --config "./fixture.yaml" projects inspect --project-name "my-project"

Use the long-form alias:

journeyapps-platform deployments list --project-name "my-project"