Imported from Nexudus-Ltd/nexudus-coworking-skills (skills/nexudus/SKILL.md). Install upstream with npx skills add Nexudus-Ltd/nexudus-coworking-skills --skill nexudus. Copyright stays with the author.

Nexudus CLI Agent Skill

You can manage Nexudus coworking spaces through the nexudus CLI tool. This skill teaches you how to authenticate, query data, and perform CRUD operations against the Nexudus platform API.

Agent Invariants

1. Always use --agent flag on every CLI call. This returns a structured JSON envelope optimised for machine consumption.

2. Parse the JSON envelope before acting on results. The envelope has this shape:

   {
     "ok": true,
     "data": { ... },
     "summary": "Human-readable summary",
     "breadcrumbs": ["entity", "action"],
     "meta": { "total": 10, "page": 1, "pageSize": 25, "totalPages": 1 }
   }

3. Check ok first. If ok is false, read summary for the error message and stop.

4. Never prompt the user for credentials interactively. If ok is false with an auth error, tell the user to run nexudus login manually.

5. Use --yes or -y on delete commands to skip interactive confirmation prompts.

6. Use --json when you need raw data for scripting. Use --agent when you want the envelope with summary.

7. List responses omit collection properties. The API only returns list/array fields (e.g., Tariffs, Teams, LinkedResources) when fetching a single entity by ID (get <id>). List commands return a simplified projection without these fields. If you need to read or verify a collection property, always fetch the individual entity first.

8. Use the current user's defaults for business, currency, country, and timezone. Before creating or updating entities that require a business (location), currency, country, or timezone, run nexudus whoami --agent and use the defaults from the response:

   • DefaultBusinessId — use as --business when creating entities scoped to a location.
   • DefaultCurrencyId — use as --currency-id when a currency is needed.
   • DefaultCurrencyCode — for display/reference purposes.
   • DefaultCountryId — use as --country-id when a country is needed.
   • DefaultSimpleTimeZoneId — use as --timezone-id when a timezone is needed.

   Only ask the user to specify these values if they explicitly want to override the defaults.

9. Prefer --{list} over --added-{list} / --removed-{list} for list properties. When setting a list field (e.g., --tariffs, --resource-types, --teams, --linked-resources), use the plain --{list} flag to replace the entire list with the supplied values. Only use --added-{list} or --removed-{list} when you specifically need to add or remove individual items from the existing list without touching the rest of its contents. Passing --added-{list} when you mean to set the full list is a common mistake that leaves stale entries in place.

10. When unsure about a field, run --help first. If the entity or option is not fully documented in this skill file, run nexudus <entity> <command> --help to discover available options and their descriptions before constructing the command.

11. DateTime values must use ISO 8601 format. All DateTime fields must be passed as YYYY-MM-DDTHH:MM:SSZ (UTC) — for example 2025-06-15T09:00:00Z. Never use locale-specific formats like June 15, 2025, 15/06/2025, or Unix timestamps. Entity reference files annotate DateTime options with (DateTime) so you can identify them.

12. Always pass telemetry context flags on every CLI call. See the Telemetry Context section below for the required flags and how to generate values.

Bootstrapping

Run diagnostics first to verify the CLI is ready:

nexudus doctor --agent

This returns CLI version, .NET runtime, OS, credential status, config file location, API connectivity, and all available commands. Check data.CredentialsStored and data.ApiStatus before proceeding.

If credentials are missing, instruct the user:

Run nexudus login to authenticate with your Nexudus account.

CLI Introspection

Discover available commands and options at any time:

nexudus --help
nexudus businesses --help
nexudus products --help
nexudus config --help

Each command also supports --help for detailed option information:

nexudus businesses update --help
nexudus products create --help

Command Reference

Authentication

Configuration

Config keys: base-url

Diagnostics

nexudus doctor --agent

Global Flags

Telemetry Context

Every CLI call from an agent must include the four telemetry flags so command usage can be tracked, correlated, and debugged.

Example: full call with telemetry

nexudus products list --agent --trace-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --caller copilot --intent "list all products" --attempt 1

Rules

• Same --trace-id for every call within the same user task / conversation turn.
• Increment --attempt only when retrying the exact same command after a failure.
• --caller must stay constant for the agent's lifetime (e.g., copilot, claude, custom-bot).
• --intent should be the user's original request, not the CLI command description.
• When --agent is set and telemetry flags are present, the response envelope includes a telemetry object with traceId, durationMs, and attempt for your reference.

Output Envelope

All commands produce a JSON envelope when --agent or --json is used:

{
  "ok": true,
  "data": [ ... ],
  "summary": "Found 3 businesses (page 1/1)",
  "breadcrumbs": ["businesses", "list"],
  "meta": {
    "total": 3,
    "page": 1,
    "pageSize": 25,
    "totalPages": 1
  }
}

• ok: true on success, false on failure.
• data: The response payload — an object for single-entity operations, an array for lists, or null on some failures.
• summary: Human-readable result description.
• breadcrumbs: Command path that produced the output (e.g., ["products", "create"]).
• meta: Pagination metadata for list operations (present only on list commands).

PII Redaction

The CLI automatically redacts personally identifiable information in non-interactive mode. This behavior is structural and not controlled by a caller flag.

• In redirected/agent output, PII values appear as deterministic tokens such as «PII:EMAIL:a3f2b1c9».
• Tokens are stable for the same source value on the same machine.
• You may pass tokens back to create/update commands; the CLI resolves them to real values before API calls.
• Non-interactive responses include piiRedaction and piiRedactionReason so you can verify mode.

Example token round-trip:

nexudus coworkers update 12345 --email "«PII:EMAIL:a3f2b1c9»" --agent

Do not treat tokens as real values and do not attempt to reverse them.

Error envelope

{
  "ok": false,
  "data": null,
  "summary": "Not logged in. Run 'nexudus login' first.",
  "breadcrumbs": ["businesses", "list"]
}

Decision Trees

"Find and display a business"

1. nexudus businesses list --agent (or use filter options like --name "value" if searching)
2. Parse data array, find the target business
3. nexudus businesses get <id> --agent for full details

"Create a entity"

1. First find the business ID: nexudus businesses list --agent
2. nexudus <entity> create --name "Day Pass" --price 25.00 --business <businessId> --agent
3. Check ok is true, read data.Id for the new entity ID

"Update a entity property"

1. nexudus <entity> get <id> --agent to verify the entity exists
2. nexudus <entity> update <id> --<property> <value> --agent
3. Verify the update by checking the returned data

"Delete a entity"

1. nexudus <entity> get <id> --agent to confirm the entity exists
2. nexudus <entity> delete <id> --yes --agent
3. Check ok is true

"List entity for a specific business"

1. nexudus <entity> list --business <businessId> --agent
2. For pagination: add --page-number N --page-size M

"Run an entity command on entity"

1. nexudus <entity> commands --agent to discover available commands
2. nexudus <entity> run-command <commandKey> <id1,id2> --agent
3. Add parameters with -p Name=Value if the command requires them

"Check CLI health"

1. nexudus doctor --agent
2. Verify data.CredentialsStored is true
3. Verify data.ApiStatus is "OK"

Entity-specific workflows (e.g., adding passes to a product, setting up pricing) are documented in the corresponding entity reference file under references/entities/.

Error Handling

Entity Index

Before working with an entity, load its reference file for full details (commands, options, key fields, enum values, and entity-specific workflows).

Image Uploads

Some entities have image properties (logo, banner, picture, etc.). To set an image, you must provide two properties:

1. New{PropertyName}Url — a publicly accessible URL where the Nexudus back-end can download the image. Local file paths or authenticated URLs will not work.
2. {PropertyName}FileName — the file name (with extension) to store for the image. Use only non-special characters (letters, digits, hyphens, underscores) and include the file extension (e.g., .png, .jpg).

If the user does not supply a file name, derive one from the URL (use the last path segment, stripping query strings and special characters) or generate a reasonable default like image.png. Always ensure the name contains only safe characters and a valid image extension.

Example — set a logo on a business:

nexudus businesses update <id> --logo-url "https://example.com/logo.png" --logo-file-name "logo.png" --agent

Example — set a picture on a resource:

nexudus resources update <id> --new-picture-url "https://example.com/room.jpg" --picture-file-name "room.jpg" --agent

Example — user provides only the URL (agent derives the file name):

# User says: set the logo to https://cdn.example.com/images/my-logo.png
# Agent extracts "my-logo.png" from the URL path
nexudus businesses update <id> --logo-url "https://cdn.example.com/images/my-logo.png" --logo-file-name "my-logo.png" --agent

Example — URL has no usable file name (agent generates one):

# User says: set the logo to https://cdn.example.com/generate?id=abc
# Agent cannot extract a file name, so it generates a safe default
nexudus businesses update <id> --logo-url "https://cdn.example.com/generate?id=abc" --logo-file-name "logo.png" --agent

Nexudus API Pattern

The Nexudus API follows a consistent REST pattern. Each entity at /api/{module}/{entities} supports:

Passing Multiple Values (List Options)

Some options accept a list of IDs (e.g., --tariffs, --teams, --linked-resources, --resource-types). To pass multiple values, repeat the flag for each value:

nexudus resources update <id> --tariffs 101 --tariffs 202 --tariffs 303 --agent

Do not use comma-separated values or bracket syntax — each value needs its own flag.

Choosing between --{list}, --added-{list}, and --removed-{list}

Every list property comes in three variants. Use the right one for your intent:

Use --{list} in almost all cases. The add/remove variants are only needed when you need surgical, incremental changes — for example, adding a single new tariff to a resource that already has several others you must not disturb.

Example — replace all tariffs on a resource:

nexudus resources update <id> --tariffs 101 --tariffs 202 --agent

Example — add one tariff without changing the existing ones:

nexudus resources update <id> --added-tariffs 303 --agent

Example — remove one tariff without changing the existing ones:

nexudus resources update <id> --removed-tariffs 101 --agent

Tips

• Use --page-size 100 to fetch larger pages when you need to scan many records.
• Use --id <id> to filter by a single ID, or repeat --id <id1> --id <id2> for multiple IDs.
• Use --unique-id <guid> to filter by UniqueId (GUID), repeatable for multiple.
• Combine filter options with pagination for efficient searching.
• The run-command accepts comma-separated IDs to batch operations: nexudus products run-command archive 123,456,789 --agent.
• Business entities cannot be created or deleted via the API — only listed, viewed, and updated.
• Always pass --yes with delete commands whegin running non-interactively.