Provision & CLI

Playbooks can be defined as YAML files, committed to git, and deployed with the provision tool. This gives you version control, reproducibility, and the ability to review changes before applying them.

---

Why use provision?

Manual (Studio UI)	Provision (YAML + CLI)
Good for building and experimenting	Good for shipping and repeating
No audit trail	Git history tracks every change
Manual steps on each deploy	Idempotent — safe to run on every deploy
Hard to review changes	--dry-run shows exactly what will change

---

Install the CLI

go install github.com/taufinity/cli/cmd/taufinity@latest

Verify:

taufinity version

---

Authenticate

taufinity auth login

Opens a browser for device authorization. Credentials are stored at ~/.config/taufinity/credentials.json.

For admin operations (provisioning), elevate your session:

taufinity auth elevate
# Enter your TOTP code when prompted
# Elevation lasts 16 hours

---

Playbook YAML schema

Save playbook files in studio/playbooks/ in your repo:

# studio/playbooks/weekly-report.yaml

name: Weekly Report
slug: weekly-report              # stable ID for provision — rename `name` freely
description: Generates a weekly ops summary from Odoo data
trigger_type: schedule           # manual | schedule | event
schedule: "0 9 * * 1"           # cron: every Monday at 9:00 AM
schedule_timezone: Europe/Amsterdam
output_key: report
enabled: true
agent_triggerable: false

steps:
  - name: Pull Odoo tasks
    step_type: odoo_read
    output_key: tasks
    config:
      credential_ref: "My Odoo"    # name of the credential in Studio
      model: project.task
      domain: '[["stage_id.fold","=",false]]'
      fields: [id, name, stage_id, date_deadline, user_ids]
      limit: 200

  - name: Summarise
    step_type: ai_prompt
    output_key: summary
    config:
      provider: anthropic
      model: claude-haiku-4-5-20251001
      max_tokens: 500
      instruction: |
        Today is {{.Date}}. Summarise these open Odoo tasks as a concise weekly ops briefing.
        Highlight overdue items.

        Tasks: {{.step_outputs.tasks}}

  - name: Export
    step_type: export_output
    output_key: report
    config:
      input_key: summary
      format: html

Key fields

Field	Required	Description
name	Yes	Display name in Studio
slug	Recommended	Stable provision key — provision uses this to match existing playbooks
trigger_type	Yes	manual, schedule, event
schedule	If scheduled	5-field cron expression
schedule_timezone	If scheduled	IANA timezone (e.g. Europe/Amsterdam)
output_key	Yes	Which step's output is the final result
enabled	Yes	true to activate
steps[].step_type	Yes	See Step Types
steps[].output_key	Yes	Key to store this step's output under
steps[].config	Varies	Step-specific config — see Step Types reference

credential_ref

Never hardcode API tokens in YAML. Reference a credential by name instead:

config:
  credential_ref: "My Odoo"

Create the credential once in Studio under Settings → Credentials, then reference it by name in any playbook.

---

Provision workflow

1. Dry-run first

cd /path/to/your-repo

go run ./cmd/provision \
  --dir studio/ \
  --org-slug my-org \
  --url https://studio.taufinity.io \
  --dry-run

Output shows what would be created, updated, or left unchanged:

playbook "Weekly Report"  →  CREATE
playbook "Daily Summary"  →  NOOP (no changes)

2. Apply

Remove --dry-run:

go run ./cmd/provision \
  --dir studio/ \
  --org-slug my-org \
  --url https://studio.taufinity.io

Provision is idempotent — re-running with the same YAML produces all NOOPs.

Auth token

Provision uses an admin token. For interactive sessions, taufinity auth elevate sets this automatically. For non-interactive use (CI), set it explicitly:

export TAUFINITY_ADMIN_TOKEN=your-admin-token
go run ./cmd/provision ...

Org slug vs org ID

--org-slug (provision) and --org (CLI commands) refer to the same organisation but use different formats:

• provision uses the slug — the URL-safe name (e.g., my-company)
• taufinity playbook list/trigger/runs uses the numeric ID (e.g., --org 12)

Find your org slug in Studio → Settings → General.

---

taufinity CLI — playbook commands

List playbooks

taufinity playbook list

ID   NAME                  TRIGGER    ENABLED
19   MT Finance Snapshot   schedule   true
20   mt-sales              schedule   true
28   mt-deck-generator     schedule   true

Override org:

taufinity playbook list --org 12

Trigger a playbook

# Trigger with no inputs
taufinity playbook trigger 28

# Trigger with inputs as JSON
taufinity playbook trigger 28 --inputs '{"topic": "AI trends"}'

Inspect recent runs

taufinity playbook runs 28

RUN_ID   STATUS    STARTED              DURATION
9841     success   2026-06-03 09:00     12.4s
9792     success   2026-05-27 09:00     11.8s
9744     failed    2026-05-20 09:00     3.1s

---

Cron quick reference

Expression	Meaning
0 9 * * *	Every day at 9:00 AM
0 9 * * 1	Every Monday at 9:00 AM
0 */2 * * *	Every 2 hours
0 0 1 * *	First day of the month at midnight
0 18 * * 4	Every Thursday at 6:00 PM

Minimum interval: 1 hour.