facilioo-agent-skill

English

Purpose

facilioo-agent-skill is an agent-first Facilioo toolkit whose product goal is broad workflow automation for property management teams. It ships as a real CLI plus a Codex-style skill payload, so an agent can install it, authenticate once, build context around properties or units, and execute Facilioo workflows through terminal commands instead of a browser.

The target direction is not just selective API access, but end-to-end automation of the important day-to-day workflows that a Hausverwaltung handles in Facilioo. That includes context building, operational case work, document handling, and conference-related work. The current release candidate already covers the operational core and is intentionally structured so deeper workflow automation can be added without redesigning the public CLI surface.

The product surface is the public CLI:

• facilioo-agent-cli
• facilioo-agent-skill

The skill explains how an agent should use that CLI safely. It is not a substitute implementation.

Current scope

• password-first authentication with persisted local session
• technical API-key login as an explicit option
• automatic session hardening through preflight refresh and one retry after 401 Unauthorized
• auth status, auth login, auth refresh, auth export, auth clear
• doctor profiles for auth, core reads, and document I/O
• context lookup for properties, entrances, units, parties, accounts, and contact details
• operational workflows for inquiries, processes, work orders, appointments, user tasks, notifications, and notices
• document search, document download, document creation via signed upload flow
• attachment workflows for inquiries, inquiry responses, and process feed entries
• conference search plus detail, agenda, protocol, topics, and resolutions
• installer that copies the skill payload into ~/.codex/skills/facilioo-agent-cli

Product direction

The long-term product goal is to make an agent capable of working through Facilioo workflows as completely as possible from the CLI.

In practice, that means:

• building the right working context quickly
• understanding open operational work across inquiries, processes, work orders, appointments, tasks, notifications, and notices
• reading, creating, linking, and downloading documents without switching surfaces
• moving through conference-related data where it matters in day-to-day administration
• keeping dangerous actions explicitly guarded instead of hiding them behind raw API calls

The current implementation should therefore be read as the first publishable automation surface, not as the final functional ceiling.

Installation

1. Install the package

npm install -g @codecell-germany/facilioo-agent-skill

This global install makes the public CLI binaries available. It does not yet copy the Codex skill payload into ~/.codex/skills/.

2. Verify the CLI

facilioo-agent-cli --help
facilioo-agent-skill --help

3. Install the skill payload for Codex

facilioo-agent-skill install --force

This second step is intentional. It installs the Codex skill payload and the local Codex shim under ~/.codex/.

Quick start

Requirements:

• Node.js >= 20
• Facilioo account with API access
• preferred: local password login by a human in a real TTY

If this is the first setup, print the built-in guide first:

facilioo-agent-cli setup --language en
facilioo-agent-cli setup --language de

Recommended static environment values:

export FACILIOO_BASE_URL="https://api.facilioo.de"
export FACILIOO_API_VERSION="2.0"
export FACILIOO_AUTH_METHOD="password"

This CLI targets the current Gen2 API surface under /api. The older OpenAPI surface is deprecated by Facilioo and is scheduled to be switched off on January 1, 2027.

Default login:

facilioo-agent-cli auth login --method password --interactive --persist

This password flow is intentionally local and interactive. It should be completed by a human in a real TTY, not by a headless or non-interactive agent loop.

Optional technical login:

export FACILIOO_API_KEY="..."
facilioo-agent-cli auth login --method api-key --persist

Do not hardcode issued tokens in code. Request them dynamically when needed and let the CLI persist the session locally.

Validate the session before doing work:

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

Only after doctor is healthy should the agent move to work commands:

facilioo-agent-cli context lookup --search "Musterstraße 12" --json
facilioo-agent-cli ops inbox --property-id 123 --json

Deterministic first-run order for agents

If a fresh agent receives this skill, the correct order is:

1. facilioo-agent-cli --help
2. facilioo-agent-cli auth status --json
3. facilioo-agent-cli doctor --profile auth --json
4. if setup is incomplete, print facilioo-agent-cli setup --language en|de
5. collect only static values first:
   • FACILIOO_BASE_URL
   • FACILIOO_API_VERSION
   • FACILIOO_AUTH_METHOD
6. use the default local password flow first when a human is available at the terminal:
   • facilioo-agent-cli auth login --method password --interactive --persist
7. only use API-key login when the user explicitly wants a technical or automation-oriented setup:
   • FACILIOO_API_KEY
   • facilioo-agent-cli auth login --method api-key --persist
8. rerun:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
9. only then start context, ops, documents, or conferences

Do not start with hidden local install paths, repo-local dist/, or raw HTTP experiments.

Example commands

Context lookup

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

owners, contracts, and responsibilities read EV-relevant master data such as owners, unit contracts, emergency contacts, responsible staff members, trades, and assigned construction parties.

Processes

facilioo-agent-cli ops processes search --property-id 123 --open-only --json
facilioo-agent-cli ops processes show --id 987 --json
facilioo-agent-cli ops processes feed --id 987 --json
facilioo-agent-cli ops processes tasks --id 987 --json
facilioo-agent-cli ops processes work-orders --id 987 --json

Process create and update

facilioo-agent-cli ops processes create \
  --set contactId=321 \
  --set typeId=4 \
  --set unitId=456 \
  --set subject="Wasserschaden Küche" \
  --set report="<p>Leck gemeldet.</p>" \
  --execute \
  --confirm-write yes \
  --json

facilioo-agent-cli ops processes update \
  --id 987 \
  --set stageId=8 \
  --set isFinished=false \
  --execute \
  --confirm-write yes \
  --json

Process delete with explicit special approval

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

The same delete rule applies to every exposed delete command in this package.

Documents

facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json
facilioo-agent-cli documents show --id 5001 --json
facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json

Create a document through the signed upload flow:

facilioo-agent-cli documents create \
  --input /absolute/path/rechnung.pdf \
  --type-id 12 \
  --title "Rechnung Sanitär" \
  --property-id 123 \
  --execute \
  --confirm-write yes \
  --json

Attachments

facilioo-agent-cli documents attachments list --target inquiry --target-id 2001 --json

facilioo-agent-cli documents attachments add \
  --target inquiry \
  --target-id 2001 \
  --input /absolute/path/foto.jpg \
  --type-id 12 \
  --execute \
  --confirm-write yes \
  --json

Conferences

facilioo-agent-cli conferences search --property-id 123 --json
facilioo-agent-cli conferences show --id 7001 --json
facilioo-agent-cli conferences agenda --id 7001 --json
facilioo-agent-cli conferences protocol --id 7001 --json
facilioo-agent-cli conferences technical-protocol --id 7001 --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

EV analysis commands default to curated, redacted JSON. Use --raw only when a human explicitly needs raw Facilioo payloads for debugging.

Guardrails

• Reads are available by default.
• EV analysis reads are redacted by default because owners, contracts, attendees, and protocols can contain personal data.
• Writes require --execute --confirm-write yes.
• Every exposed delete requires --execute --allow-delete --confirm-delete yes.
• --preview should be used before sensitive changes or deletes.
• Password login is interactive only.
• Tokens are never printed in normal status or doctor output.
• auth export is explicit and opt-in for cross-process handoff.
• Public docs and examples use placeholders only.

Auth and session model

The CLI is static-env-first and persisted-session-first.

Static values still come from environment variables:

• FACILIOO_BASE_URL
• FACILIOO_API_VERSION
• FACILIOO_AUTH_METHOD
• optional: FACILIOO_API_KEY

After auth login, the CLI persists the live session locally. On macOS it prefers the Keychain. Business commands automatically refresh old sessions before work starts and retry once after 401 Unauthorized. auth export exists only as an explicit bridge for another shell process.

Useful commands:

facilioo-agent-cli auth status --json
facilioo-agent-cli auth refresh --json
facilioo-agent-cli auth export --write-env-file ~/.config/facilioo-agent-cli/session.env --json
facilioo-agent-cli auth clear --json

Privacy and publish hygiene

This package is intentionally published with a strict npm file whitelist. Private planning and research data are not part of the public package surface.

That means:

• Plans/ is private
• repo-local research and knowledge notes are private
• .env* is private
• tarballs and local output folders stay private

References

• skills/facilioo-agent-cli/SKILL.md
• skills/facilioo-agent-cli/references/overview.md
• skills/facilioo-agent-cli/references/agent-onboarding.md
• skills/facilioo-agent-cli/references/facilioo-first-run.md
• skills/facilioo-agent-cli/references/command-cheatsheet.md

Deutsch

Zweck

facilioo-agent-skill ist ein agentenorientiertes Facilioo-Toolkit mit dem Produktziel, Arbeitsabläufe einer Hausverwaltung in Facilioo möglichst umfassend zu automatisieren. Es besteht aus einer echten CLI plus einem Codex-Skill-Payload, sodass ein Agent es installieren, sich einmal authentifizieren, Kontext zu Objekten oder Einheiten aufbauen und Facilioo-Workflows per Terminal statt über den Browser ausführen kann.

Die Zielrichtung ist nicht nur selektiver API-Zugriff, sondern eine Ende-zu-Ende-Automatisierung der wichtigen Tagesgeschäfts-Workflows einer Hausverwaltung in Facilioo. Dazu gehören Kontextaufbau, operative Fallbearbeitung, Dokumentenarbeit und konferenzbezogene Abläufe. Der aktuelle veröffentlichbare Stand deckt bereits den operativen Kern ab und ist bewusst so aufgebaut, dass tiefere Workflow-Automatisierung später ohne Redesign der öffentlichen CLI-Oberfläche ergänzt werden kann.

Die öffentliche Produktoberfläche ist:

• facilioo-agent-cli
• facilioo-agent-skill

Der Skill erklärt, wie ein Agent diese CLI sicher verwenden soll. Er ist keine alternative Implementierung.

Aktueller Umfang

• passwortbasierte Standard-Authentifizierung mit lokal persistierter Session
• technischer API-Key-Login als explizite Option
• automatische Session-Härtung durch Preflight-Refresh und einen Retry nach 401 Unauthorized
• auth status, auth login, auth refresh, auth export, auth clear
• doctor-Profile für Auth, Core-Reads und Dokumenten-I/O
• Kontextsuche für Objekte, Eingänge, Einheiten, Parteien, Konten und Kontaktdaten
• operative Workflows für Anfragen, Vorgänge, Work Orders, Termine, User Tasks, Notifications und Notices
• Dokumentensuche, Dokumentendownload und Dokumentenerstellung über den signierten Upload-Flow
• Anhangs-Workflows für Anfragen, Anfrageantworten und Prozess-Feed-Einträge
• Konferenzsuche sowie Details, Agenda, Protokoll, Themen und Beschlüsse
• Installer, der den Skill-Payload nach ~/.codex/skills/facilioo-agent-cli kopiert

Produktrichtung

Das langfristige Produktziel ist, einen Agenten dazu zu befähigen, Facilioo-Workflows so vollständig wie möglich über die CLI zu bearbeiten.

Praktisch bedeutet das:

• den richtigen Arbeitskontext schnell aufbauen
• offene operative Arbeit über Anfragen, Vorgänge, Work Orders, Termine, Tasks, Notifications und Notices verstehen
• Dokumente lesen, erstellen, verknüpfen und herunterladen, ohne die Oberfläche zu wechseln
• konferenzbezogene Daten dort bearbeiten, wo sie im Verwaltungsalltag relevant sind
• gefährliche Aktionen explizit absichern, statt sie hinter rohen API-Calls zu verstecken

Die aktuelle Umsetzung ist deshalb als erste veröffentlichbare Automatisierungsoberfläche zu lesen, nicht als endgültige Funktionsgrenze.

Installation

1. Paket installieren

npm install -g @codecell-germany/facilioo-agent-skill

Diese globale Installation macht die öffentlichen CLI-Binaries verfügbar. Sie kopiert den Codex-Skill-Payload noch nicht nach ~/.codex/skills/.

2. CLI prüfen

facilioo-agent-cli --help
facilioo-agent-skill --help

3. Skill-Payload für Codex installieren

facilioo-agent-skill install --force

Dieser zweite Schritt ist beabsichtigt. Er installiert den Codex-Skill-Payload und den lokalen Codex-Shim unter ~/.codex/.

Schnellstart

Voraussetzungen:

• Node.js >= 20
• Facilioo-Konto mit API-Zugang
• bevorzugt: Zugang über den normalen Benutzerlogin

Wenn dies die erste Einrichtung ist, zuerst den eingebauten Guide ausgeben:

facilioo-agent-cli setup --language en
facilioo-agent-cli setup --language de

Empfohlene statische Umgebungswerte:

export FACILIOO_BASE_URL="https://api.facilioo.de"
export FACILIOO_API_VERSION="2.0"
export FACILIOO_AUTH_METHOD="password"

Diese CLI zielt auf die aktuelle Gen2-API-Oberfläche unter /api. Die ältere OpenAPI-Oberfläche ist laut Facilioo veraltet und soll am 1. Januar 2027 abgeschaltet werden.

Standard-Login:

facilioo-agent-cli auth login --method password --interactive --persist

Dieser Passwort-Flow ist bewusst lokal und interaktiv. Er sollte von einem Menschen in einem echten TTY abgeschlossen werden, nicht von einem headless oder nicht-interaktiven Agentenloop.

Optionaler technischer Login:

export FACILIOO_API_KEY="..."
facilioo-agent-cli auth login --method api-key --persist

Tokens sollten nicht fest im Code hinterlegt werden. Sie sollten bei Bedarf dynamisch angefordert werden, während die CLI die Session lokal persistiert.

Vor echter Arbeit die Session validieren:

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

Erst wenn doctor gesund ist, sollte der Agent zu Arbeitskommandos wechseln:

facilioo-agent-cli context lookup --search "Musterstraße 12" --json
facilioo-agent-cli ops inbox --property-id 123 --json

Deterministische Erstreihenfolge für Agenten

Wenn ein frischer Agent diesen Skill erhält, ist die richtige Reihenfolge:

1. facilioo-agent-cli --help
2. facilioo-agent-cli auth status --json
3. facilioo-agent-cli doctor --profile auth --json
4. wenn das Setup unvollständig ist, facilioo-agent-cli setup --language en|de ausgeben
5. zuerst nur statische Werte einsammeln:
   • FACILIOO_BASE_URL
   • FACILIOO_API_VERSION
   • FACILIOO_AUTH_METHOD
6. wenn ein Mensch am Terminal verfügbar ist, zuerst den lokalen Passwort-Flow verwenden:
   • facilioo-agent-cli auth login --method password --interactive --persist
7. API-Key-Login nur verwenden, wenn der Nutzer ausdrücklich ein technisches oder stärker automatisiertes Setup möchte:
   • FACILIOO_API_KEY
   • facilioo-agent-cli auth login --method api-key --persist
8. danach erneut ausführen:
   • facilioo-agent-cli auth status --json
   • facilioo-agent-cli doctor --profile core-read --json
9. erst dann mit context, ops, documents oder conferences beginnen

Nicht mit versteckten lokalen Installationspfaden, repo-lokalem dist/ oder rohen HTTP-Experimenten starten.

Beispielkommandos

Kontextsuche

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

owners, contracts und responsibilities lesen EV-relevante Stammdaten wie Eigentümer, Einheitsverträge, Notfallkontakte, zuständige Mitarbeitende, Gewerke und zugewiesene ausführende Firmen.

Vorgänge

facilioo-agent-cli ops processes search --property-id 123 --open-only --json
facilioo-agent-cli ops processes show --id 987 --json
facilioo-agent-cli ops processes feed --id 987 --json
facilioo-agent-cli ops processes tasks --id 987 --json
facilioo-agent-cli ops processes work-orders --id 987 --json

Vorgang anlegen und aktualisieren

facilioo-agent-cli ops processes create \
  --set contactId=321 \
  --set typeId=4 \
  --set unitId=456 \
  --set subject="Wasserschaden Küche" \
  --set report="<p>Leck gemeldet.</p>" \
  --execute \
  --confirm-write yes \
  --json

facilioo-agent-cli ops processes update \
  --id 987 \
  --set stageId=8 \
  --set isFinished=false \
  --execute \
  --confirm-write yes \
  --json

Vorgang löschen nur mit ausdrücklicher Sonderfreigabe

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

Dieselbe Delete-Regel gilt für jeden öffentlich exponierten Delete-Befehl in diesem Paket.

Dokumente

facilioo-agent-cli documents search --property-id 123 --search "Versicherung" --json
facilioo-agent-cli documents show --id 5001 --json
facilioo-agent-cli documents download --id 5001 --output /absolute/path/file.pdf --json

Dokument über den signierten Upload-Flow anlegen:

facilioo-agent-cli documents create \
  --input /absolute/path/rechnung.pdf \
  --type-id 12 \
  --title "Rechnung Sanitär" \
  --property-id 123 \
  --execute \
  --confirm-write yes \
  --json

Anhänge

facilioo-agent-cli documents attachments list --target inquiry --target-id 2001 --json

facilioo-agent-cli documents attachments add \
  --target inquiry \
  --target-id 2001 \
  --input /absolute/path/foto.jpg \
  --type-id 12 \
  --execute \
  --confirm-write yes \
  --json

Konferenzen

facilioo-agent-cli conferences search --property-id 123 --json
facilioo-agent-cli conferences show --id 7001 --json
facilioo-agent-cli conferences agenda --id 7001 --json
facilioo-agent-cli conferences protocol --id 7001 --json
facilioo-agent-cli conferences technical-protocol --id 7001 --json
facilioo-agent-cli conferences context --id 7001 --json
facilioo-agent-cli conferences match-transcript --conference-id 7001 --input /absolute/path/transkript.txt --json
facilioo-agent-cli conferences implementation-plan --conference-id 7001 --input /absolute/path/finales-protokoll.txt --preview --json

EV-Analysebefehle liefern standardmäßig kuratierte, redigierte JSON-Ausgaben. --raw nur verwenden, wenn ein Mensch Rohdaten ausdrücklich zur Diagnose braucht.

Guardrails

• Reads sind standardmäßig verfügbar.
• EV-Analyse-Reads sind standardmäßig redigiert, weil Eigentümer, Verträge, Teilnehmer und Protokolle personenbezogene Daten enthalten können.
• Writes erfordern --execute --confirm-write yes.
• Jeder exponierte Delete erfordert --execute --allow-delete --confirm-delete yes.
• --preview sollte vor sensiblen Änderungen oder Deletes verwendet werden.
• Passwort-Login ist nur interaktiv.
• Tokens werden in normaler Status- oder Doctor-Ausgabe nie ausgegeben.
• auth export ist explizit opt-in für prozessübergreifende Übergabe.
• Öffentliche Doku und Beispiele verwenden nur Platzhalter.

Auth- und Session-Modell

Die CLI ist static-env-first und persisted-session-first.

Statische Werte kommen weiterhin aus Umgebungsvariablen:

• FACILIOO_BASE_URL
• FACILIOO_API_VERSION
• FACILIOO_AUTH_METHOD
• optional: FACILIOO_API_KEY

Nach auth login persistiert die CLI die Live-Session lokal. Auf macOS bevorzugt sie die Keychain. Fachkommandos erneuern alte Sessions automatisch vor Arbeitsbeginn und wiederholen einen Request einmal nach 401 Unauthorized. auth export existiert nur als explizite Brücke für einen anderen Shell-Prozess.

Nützliche Befehle:

facilioo-agent-cli auth status --json
facilioo-agent-cli auth refresh --json
facilioo-agent-cli auth export --write-env-file ~/.config/facilioo-agent-cli/session.env --json
facilioo-agent-cli auth clear --json

Datenschutz und Publish-Hygiene

Dieses Paket wird bewusst mit einer strikten npm-Datei-Whitelist veröffentlicht. Private Planungs- und Rechercheartefakte gehören nicht zur öffentlichen Paketoberfläche.

Das bedeutet:

• Plans/ ist privat
• repo-lokale Recherche- und Knowledge-Notizen sind privat
• .env* ist privat
• Tarballs und lokale Output-Ordner bleiben privat

Referenzen

• skills/facilioo-agent-cli/SKILL.md
• skills/facilioo-agent-cli/references/overview.md
• skills/facilioo-agent-cli/references/agent-onboarding.md
• skills/facilioo-agent-cli/references/facilioo-first-run.md
• skills/facilioo-agent-cli/references/command-cheatsheet.md