Purpose

Provide a stable, agent-optimized workflow for using fpt-cli from OpenClaw.

This skill follows the Agent DX principles from "You Need to Rewrite Your CLI for AI Agents":

• - optimize for predictability over discoverability
• keep context window usage low (fetch only what you need)
• enforce deep defense against hallucinated inputs
• use schema introspection at runtime instead of relying on pre-trained knowledge

Keep the agent behavior aligned with the repository contract:

• - prefer explicit CLI commands over ad-hoc API calls
• prefer JSON output for machine consumption
• prefer capability discovery before composing new command invocations
• prefer safe write previews before real mutations

When to use

Use this skill when any of the following is needed:

• - install or update INLINECODE1
• configure ShotGrid / FPT authentication for OpenClaw
• inspect which commands the CLI already exposes
• query schema or entities through the CLI
• run complex searches with filter_dsl, structured search, or INLINECODE4
• perform write operations with --dry-run first

Workflow

1. Choose the execution mode

Determine whether the task should use a released binary or a source checkout.

• - For released binary installation or update, read references/install-and-auth.md and prefer release archives plus checksum verification over pipe-to-shell installers.
• For repository-local development, prefer vx cargo run -p fpt-cli -- ... and vx just ....

2. Prefer environment-based authentication

Load credentials through environment variables instead of putting secrets directly on the command line. Never trigger browser-based OAuth flows in headless environments.

Preferred variables:

Variable	Required	Auth modes	Description
INLINECODE9	required	all	Full URL of the ShotGrid / FPT site, e.g. INLINECODE10
INLINECODE11

required | all | Auth strategy: script, user_password, or session_token |
| FPT_SCRIPT_NAME | required | script | Name of the API script credential registered in ShotGrid |
| FPT_SCRIPT_KEY | required | script | Secret key for the script credential; quote the value when it contains special characters |
| FPT_USERNAME | required | user_password | ShotGrid user login (usually an email address) |
| FPT_PASSWORD | required | user_password | Password for the ShotGrid user account |
| FPT_AUTH_TOKEN | optional | user_password | One-time 2FA token; only needed when the site enforces two-factor authentication |
| FPT_SESSION_TOKEN | required | session_token | A pre-obtained ShotGrid session token; use when script or password credentials are unavailable |
| FPT_API_VERSION | optional | all | Override the ShotGrid REST API version, e.g. v1.1; defaults to the CLI built-in value when omitted |

Allow SG_* variables only as compatibility fallback when FPT_* is not available.

3. Schema introspection — do not guess

Do not rely on pre-trained knowledge to determine command signatures or entity/field names. Pre-trained knowledge goes stale. Guessing causes syntax errors and hallucinates parameters.

Pattern: fetch command list first, then fetch only the contracts you need.

CODEBLOCK0

Using inspect list before inspect command keeps context window usage low.
Using capabilities returns the full payload for all commands — use it only when you need an overview.

4. Choose the narrowest useful command

Prefer the smallest command that satisfies the task.

• - Use entity.get when the entity id is known.
• Use entity.find-one when only one match is needed.
• Use entity.find when multiple matches or collection metadata are needed.
• Use entity.batch.* when repeating the same operation over many inputs.
• Use entity.batch.count when counting records across multiple entity types — do not call entity.count once per type.
• Use schema.entities and schema.fields before guessing entity or field names.

5. Context window discipline

Large API responses can consume significant context window and degrade reasoning.

Always limit the fields you request:

CODEBLOCK1

Do not request all fields when you only need a few.
Use entity.batch.* commands instead of looping single-entity calls.

6. Prefer structured JSON output

Default to --output json unless a human explicitly needs a different view.

This keeps OpenClaw orchestration stable and lowers prompt/token overhead.

7. Apply input hardening invariants

The CLI validates inputs against hallucination patterns. These checks cannot be bypassed:

• - Entity type names must not contain ? or # — do not embed query parameters in entity names.

Wrong: entity get "Shot?fields=code" 123 Right: entity get Shot 123 --fields code

• - Entity type names must not contain control characters (below ASCII 0x20).
• Do not pre-encode URLs — the CLI handles percent-encoding automatically. Sending %2e%2e instead of .. will cause double-encoding failures.
• Resource IDs are numeric — never embed filter expressions or query parameters in an ID argument.

The CLI operates in a zero-trust model: all inputs are validated as if they came from an untrusted source.

8. Prefer native search features for complex queries

For non-trivial filters:

• - prefer structured search JSON when building native _search payloads
• use additional_filter_presets for "latest"-style workflows
• use --filter-dsl for concise human-authored boolean logic

Read references/query-patterns.md for examples.

9. Apply write safety rules

For writes:

• - run --dry-run first when supported — treat dry-run output as the request-plan contract
• review the dry-run plan to confirm there are no hallucinated parameters before executing
• require explicit confirmation before real deletes (--yes)

CODEBLOCK2

10. Debug in a contract-first order

When something fails:

1. 1. validate auth with INLINECODE57
2. inspect the command contract with INLINECODE58
3. confirm entity and field names via schema commands
4. reduce the command to the smallest JSON-shaped reproduction
5. only then expand to batch or write workflows

References

• - INLINECODE59
• INLINECODE60