lua status

lua status (alias lua describe) reports the state of the CLI install, your credential, the current project, and how each local primitive compares with the server, in one run. It reads only; nothing is written locally or on the server. Verified against lua-cli 3.33.0.

Synopsis

lua status [--json]
lua describe [--json]

Description

The report has these sections: environment (CLI version and channel, Node, OS, install method, API and auth base URLs, which LUA_* overrides are set), updates (current and latest CLI version), auth, project, one primitives entry per kind (skills, webhooks, triggers, jobs, preprocessors, postprocessors, MCP servers, devices, device triggers, voices, workflows), persona, backup, telemetry, warnings, and hints. The command degrades instead of failing. Outside a project, project.inProject is false and primitives is empty. Without a usable credential, auth.authenticated is false, auth.serverReachable says whether the API answered, and the server side of every comparison is skipped. A section that cannot be gathered adds a line to warnings rather than aborting. The exit code is 0 in all of these cases, so automation must read the fields, not the exit code. For each primitive kind, local lists the entries in lua.skill.yaml, server lists what the agent has, and diffs gives one status per local entry: synced (local version equals the active server version), ahead (local is newer; push it, then lua version create and lua version promote, or lua deploy <type>), behind (local is older; run lua sync), or not deployed (registered without an active version, or no local version). MCP servers have no versions and are synced when present. orphans lists active server entries with no local counterpart, each with a cleanupCommand; orphaned preprocessors and postprocessors are marked critical because they run on every message. auth.source names where the credential came from: environment for the LUA_API_KEY variable, stored for the credentials file, or renewable session for an email sign-in. A scoped API key adds credentialClass: "typed-personal" and reports email and userId as null. persona.status is synced, drift, or unknown; backup.status is synced, out-of-sync, never-compiled, or unknown. hints lists follow-up commands derived from the report (lua update, lua auth configure, orphan cleanup, lua push backup, lua sync); it is empty when LUA_NO_HINTS is set.

Arguments

None.

Options

Option	Description	Default
`--json`	Print the report as one line of JSON with `schemaVersion: 1`, suppressing all progress output.	off

Output

The JSON report, formatted for readability and trimmed to two primitive kinds; the project’s lua.skill.yaml had lost its postprocessor row, so the server’s active postprocessor appears as an orphan:

Output

{
  "schemaVersion": 1,
  "command": "status",
  "generatedAt": "2026-09-12T21:40:55.755Z",
  "environment": {
    "cliVersion": "3.33.0",
    "channel": "latest",
    "nodeVersion": "v26.5.0",
    "platform": "darwin",
    "arch": "arm64",
    "osRelease": "24.6.0",
    "installMethod": "homebrew-or-npm-global",
    "execPath": "/opt/homebrew/Cellar/node/26.5.0_1/bin/node",
    "configDir": "/Users/me/.lua-cli",
    "apiBase": "https://api.heylua.ai",
    "authBase": "https://auth.heylua.ai",
    "envOverrides": {
      "LUA_API_URL": null,
      "LUA_AUTH_URL": null,
      "LUA_API_KEY": "not set",
      "LUA_TELEMETRY": null,
      "LUA_NO_HINTS": null
    }
  },
  "updates": {
    "current": "3.33.0",
    "latest": "3.33.0",
    "available": false,
    "lastCheckedAt": "2026-09-12T09:20:35.347Z",
    "fromCache": true
  },
  "auth": {
    "authenticated": true,
    "source": "renewable session",
    "email": "[email protected]",
    "userId": "user_…",
    "organizations": [
      {
        "id": "org_…",
        "name": "Claude Plugin E2E"
      }
    ],
    "serverReachable": true,
    "reachabilityMs": 9136
  },
  "project": {
    "inProject": true,
    "rootDir": "/Users/me/helpdesk-triage",
    "configPath": "/Users/me/helpdesk-triage/lua.skill.yaml",
    "agentId": "agent_…",
    "agentName": "helpdesk-triage",
    "manifest": {
      "found": true,
      "primitiveCount": 7
    }
  },
  "primitives": [
    {
      "kind": "skill",
      "displayName": "skills",
      "local": [
        {
          "name": "tickets",
          "version": "1.0.3",
          "entityId": "…"
        }
      ],
      "server": [
        {
          "name": "tickets",
          "activeVersion": "1.0.3",
          "active": true
        }
      ],
      "diffs": [
        {
          "name": "tickets",
          "localVersion": "1.0.3",
          "serverVersion": "1.0.3",
          "status": "synced"
        }
      ],
      "orphans": []
    },
    …
    {
      "kind": "postprocessor",
      "displayName": "postprocessors",
      "local": [],
      "server": [
        {
          "name": "ticket-footer",
          "activeVersion": "1.0.3",
          "active": true
        }
      ],
      "diffs": [],
      "orphans": [
        {
          "name": "ticket-footer",
          "cleanupCommand": "lua postprocessors delete --postprocessor-name \"ticket-footer\"",
          "critical": true
        }
      ]
    },
    …
  ],
  "persona": {
    "status": "synced"
  },
  "backup": {
    "status": "out-of-sync"
  },
  "telemetry": {
    "enabled": true,
    "envOverride": false
  },
  "warnings": [],
  "hints": [
    {
      "command": "lua postprocessors delete --postprocessor-name \"ticket-footer\"",
      "reason": "Remove orphan postprocessors \"ticket-footer\" (causes errors)"
    },
    {
      "command": "lua push backup",
      "reason": "Sync source backup"
    }
  ]
}

An orphan entry has name, cleanupCommand, and critical only; the server version is in the kind’s server list. warnings is an array of strings, each prefixed with the section that failed (config:, auth:, updates:, primitives:, persona:, backup:, telemetry:) or Failed to fetch server state for <kind>:. A lua.skill.yaml that does not parse is reported there and the command still exits 0:

Output

{
  "project": {
    "inProject": false,
    …
  },
  "warnings": [
    "config: missed comma between flow collection entries (2:10)\n\n 1 | agent: [unclosed\n 2 |   agentId: x\n--------------^"
  ],
  "hints": []
}

Outside a project the project, primitives, persona, and backup sections degrade to:

Output

{
  "project": {
    "inProject": false,
    "rootDir": null,
    "configPath": null,
    "agentId": null,
    "agentName": null,
    "manifest": {
      "found": false,
      "primitiveCount": 0
    }
  },
  "primitives": [],
  "persona": {
    "status": "unknown"
  },
  "backup": {
    "status": "unknown"
  },
  "warnings": [],
  "hints": []
}

Examples

Print the human-readable report:

lua status

Confirm the credential works in CI, then list every primitive that is not synced:

lua status --json --ci | jq -e '.auth.authenticated'
lua status --json --ci | jq '[.primitives[].diffs[] | select(.status != "synced")]'

Print the commands the report recommends:

lua status --json | jq -r '.hints[].command'

Exit codes

Code	Meaning
`0`	Report printed, including when unauthenticated, outside a project, or with entries in `warnings`.
`1`	An unexpected failure escaped every section; the `✖` line says what.

SDK

CLI

REST API

Synopsis

Description

Arguments

Options

Output

Examples

Exit codes

See also

​Synopsis

​Description

​Arguments

​Options

​Output

​Examples

​Exit codes

​See also

Synopsis

Description

Arguments

Options

Output

Examples

Exit codes

See also