facilioo-agent-cli

When to use

Use this skill when a task requires real work inside Facilioo and the preferred surface is a terminal workflow rather than the web UI.

Use it especially when an agent must:

• authenticate against Facilioo from the terminal,
• build context around a property, entrance, unit, or contact,
• inspect inquiries, processes, work orders, appointments, user tasks, notices, or notifications,
• download or upload documents,
• work through a conference agenda or protocol,
• perform guarded updates without improvising raw HTTP calls.

Preconditions

• Treat facilioo-agent-cli as the product surface.
• First verify that it exists on PATH:
  • facilioo-agent-cli --help
  • facilioo-agent-skill --help
• If it is missing, install it through the public package:
  • npm install -g @codecell-germany/facilioo-agent-skill
  • facilioo-agent-skill install --force
• Do not bypass the public CLI by probing repo-local dist/, hidden Codex tool folders, or old local shims.
• Do not start with ad-hoc Swagger calls when the CLI already exposes the workflow.

First-run detection

Run this before any actual Facilioo work:

facilioo-agent-cli auth status --json
facilioo-agent-cli doctor --profile auth --json

Treat the environment as not ready if any of these are true:

• the CLI is missing
• no persisted session exists
• the configured auth method is API-key login but no API key is available
• doctor fails
• the user says this is the first setup

If setup is incomplete, switch into onboarding mode immediately. Do not start with context, ops, documents, or conferences.

Onboarding mode

This is the exact first-run order for a new or partially configured user:

1. Tell the user setup is not complete yet.
2. Print the built-in setup guide in the user's preferred language:
   • English: facilioo-agent-cli setup --language en
   • German: facilioo-agent-cli setup --language de
3. Collect only the static values first:
   • FACILIOO_BASE_URL
   • FACILIOO_API_VERSION
   • FACILIOO_AUTH_METHOD
4. Default to the local password flow when a human is present at the terminal:
   • facilioo-agent-cli auth login --method password --interactive --persist
5. Use API-key login only if the user explicitly wants a technical or automation-oriented setup:
   • FACILIOO_API_KEY
   • facilioo-agent-cli auth login --method api-key --persist
6. Never ask for:
   • access tokens
   • refresh tokens
   • raw browser cookies
7. After login, rerun:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
8. Only then continue to business commands.

Core workflow

1. Validate setup:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
2. Build context:
   • facilioo-agent-cli context lookup --search "Musterstraße 12" --json
   • facilioo-agent-cli context property --id 123 --include entrances,units,tenant,documents,ops,owners,contracts,responsibilities --json
   • facilioo-agent-cli context unit --id 456 --include documents,ops --json
3. Work operational queues:
   • facilioo-agent-cli ops inbox --property-id 123 --json
   • facilioo-agent-cli ops processes search --property-id 123 --open-only --json
   • facilioo-agent-cli ops tasks mine --json
   • facilioo-agent-cli ops notifications mine --json
4. Work documents:
   • facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json
   • facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json
5. Work conferences:
   • facilioo-agent-cli conferences search --property-id 123 --json
   • facilioo-agent-cli conferences context --id 7001 --json
   • facilioo-agent-cli conferences match-transcript --conference-id 7001 --input /absolute/path/transcript.txt --json
   • facilioo-agent-cli conferences implementation-plan --conference-id 7001 --input /absolute/path/final-protocol.txt --preview --json

Guardrails

• Read operations are safe by default.
• EV analysis reads are redacted by default because owners, contracts, attendees, and protocols can contain personal data.
• Object master-data for EV workflows is read via context property --include owners,contracts,responsibilities. This includes owners, unit contracts, emergency contacts, responsible staff members, trades, and assigned construction parties.
• Writes require:
  • --execute --confirm-write yes
• Every exposed delete requires:
  • --execute --allow-delete --confirm-delete yes
• Use --preview before sensitive changes or deletes.
• Password login is interactive only and should be completed locally by a human in a real TTY.
• Persisted sessions are long-lived in practice: business commands preflight-refresh stale sessions and retry once after 401 Unauthorized.
• auth export is opt-in and should be used only when another process explicitly needs env exports.
• Do not paste tokens into prompts, tickets, chats, or screenshots.
• Do not paste raw transcripts or raw protocol text into prompts, tickets, chats, screenshots, or public docs.
• Do not treat raw API paths as the normal route when a high-level command exists.

Delete rule

The delete rule is global in this skill, not process-specific only.

Examples:

facilioo-agent-cli ops processes delete --id 987 --preview --json
facilioo-agent-cli ops processes delete --id 987 --execute --allow-delete --confirm-delete yes --json

facilioo-agent-cli documents delete --id 5001 --preview --json
facilioo-agent-cli documents delete --id 5001 --execute --allow-delete --confirm-delete yes --json

If the user has not explicitly approved a delete, do not run it.

References

• Agent onboarding runbook: references/agent-onboarding.md
• Main overview: references/overview.md
• Command cheat sheet: references/command-cheatsheet.md
• First-run setup: references/facilioo-first-run.md
• EV transcript workflow: references/ev-workflow.md