Structured Input
Use --input and --input-file for Faurya CLI commands that require structured JSON fields.
Structured Input
Some commands need fields that do not fit neatly into positional arguments or simple flags. Use --input for a JSON object inline, or --input-file for a UTF-8 JSON object stored in a file.
Rules
| Rule | Behavior |
|---|---|
| Object root | Input must be exactly one JSON object. Arrays, strings, and numbers are rejected as the root value. |
| Mutual exclusivity | Use --input or --input-file, not both. |
| File size | --input-file accepts files up to 256 KiB. |
| Merge behavior | Top-level input fields become operation arguments unless they are reserved wrapper fields. |
| Wrapper fields | arguments, filters, pagination, websiteId, and resourceId are treated specially. |
| Positional precedence | Positional IDs in the command, such as <websiteId> and <funnelId>, override IDs from input. |
| Explicit flag precedence | Explicit CLI flags such as --name, --kpi, data flags, filters, limit, and cursor override overlapping input fields. |
Inline input
faurya analytics journeys find <websiteId> --input '{"steps":[{"type":"page","value":"/pricing"}]}'Input files
Use a file for larger objects.
faurya funnels create <websiteId> --input-file ./funnel.jsonDo not include response examples in automation docs or logs. Treat input files that contain email addresses, business logic, or configuration details as sensitive project files.
Reserved wrapper fields
| Field | Purpose |
|---|---|
arguments | Object merged into command arguments. |
filters | Structured filter object or array where accepted. |
pagination | Object containing pagination fields such as limit and cursor. |
websiteId | Optional in input but overridden by positional <websiteId>. |
resourceId | Optional in input but overridden by positional resource IDs such as <funnelId>, <alertId>, or <tokenId>. |
Commands that require or commonly use structured input
| Area | Commands |
|---|---|
| Journeys | analytics journeys find requires steps. |
| Funnel analysis | funnels analyze requires steps. |
| Saved funnels | funnels create, funnels update. |
| Analytics paths and changes | analytics paths, analytics changes. |
| Payments, attribution, AI crawls | Optional structured fields for specialized query options. |
| Website settings | website update, domain commands, dashboard layout, widgets, reports, exclusions. |
| Setup instructions | Tracking, code, validation, goal code, scroll-goal code, widget embed, AI crawler setup, integration setup. |
| Teams | teams invite, teams remove. |
| Alerts | alerts create, alerts update. |
| Site API keys | tokens create can use a display name through input or --name. |
Common input shapes
Journey search
Fields: steps, optional scope, optional match, optional period, optional limit.
faurya analytics journeys find <websiteId> --input '{"steps":[{"type":"page","value":"/"},{"type":"goal","value":"signup"}],"scope":"session","match":"loose","limit":50}'Funnel analysis
Fields: steps, optional period, optional dimensions, optional limit.
faurya funnels analyze <websiteId> --input '{"steps":[{"type":"page","value":"/"},{"type":"goal","value":"signup"}],"limit":100}'Saved funnels
Create requires name and steps. Update accepts name, steps, or both.
faurya funnels create <websiteId> --input-file ./funnel.jsonfaurya funnels update <websiteId> <funnelId> --input-file ./funnel-update.jsonAlerts
Create requires a recipient and one or more goal events. Update requires at least one changed field.
faurya alerts create <websiteId> --input '{"alertName":"Signup alert","goalEvents":["signup"],"recipientEmail":"alerts@example.com","enabled":true}'faurya alerts update <websiteId> <alertId> --input '{"enabled":false}'Website settings
Use explicit fields for settings and configuration changes.
faurya website update <websiteId> --input '{"timezone":"UTC","currency":"USD"}'faurya website dashboard layout <websiteId> --input '{"componentOrder":["kpis","chart","sources","pages"]}'faurya website widgets enable <websiteId> --input '{"enabled":true}'faurya website exclusions add <websiteId> --input '{"type":"path","value":"/internal"}'Domains
faurya website domain set <websiteId> --input '{"domain":"example.com"}'faurya website domain add <websiteId> --input '{"domain":"app.example.com"}'Setup and integrations
Use structured input to select platform, code type, validation data, widget type, provider environment, or goal details.
faurya website setup tracking <websiteId> --input '{"platform":"script","environment":"production"}'faurya website setup code <websiteId> --input '{"codeType":"script"}'faurya website setup validate <websiteId> --input-file ./tracking-validation.jsonfaurya website widgets embed <websiteId> --input '{"widgetType":"realtime","loading":"lazy"}'faurya website integrations setup <websiteId> <provider> --input '{"environment":"live"}'Team management
faurya teams invite <websiteId> --input '{"email":"teammate@example.com","role":"guest"}'faurya teams remove <websiteId> <memberId> --input '{"email":"teammate@example.com"}'Site API-key creation
faurya tokens create <websiteId> --input '{"name":"Deploy key"}'You can also use the explicit name flag:
faurya tokens create <websiteId> --name "Deploy key"