[cmarguta-alg]

🤔 What

Adds --file / -f (and - for stdin) next to inline --json on Agent Studio create/update commands that take a JSON payload.

🤷 Why

#290 ships providers create/update with --json only. Large payloads and API keys are awkward on argv. --file is an additional source, not a replacement.

🔍 How

Section Group	Change
Commands	agentstudio agents create/update and agentstudio providers create/update accept --file / -f.
Helper	cmdutil.JSONPayload reads --json or --file (including - via existing ReadFile).
Exclusivity	--json and --file cannot be combined with each other or with name/instructions flags.

--json still works. File contents are trimmed; parsing errors stay parsing agent JSON / parsing provider JSON.

🧪 Testing

Stacked on #290. Merge #289, #288, then #290 first, or check out this branch which includes them.

Writes need editSettings (admin keys skip the CLI ACL check). Replace <APP_ID> with an Agent Studio app. Pass --application-id if the selected profile app does not resolve. Do not commit files that contain real API keys.

Quick checks

task build
go test ./pkg/cmdutil ./pkg/cmd/agents/create ./pkg/cmd/agents/update ./pkg/cmd/providers/create ./pkg/cmd/providers/update -count=1
./algolia agentstudio agents create --help
./algolia agentstudio providers create --help

Expect tests green and --file documented beside --json.

Scenario 1 — agents create from file

Action: write a payload file, create an agent from it, then from stdin.

cat > /tmp/agent.json <<'JSON'
{"name":"cli-file-agent","instructions":"You are a helpful assistant."}
JSON

./algolia agentstudio agents create --application-id <APP_ID> --file /tmp/agent.json
cat /tmp/agent.json | ./algolia agentstudio agents create --application-id <APP_ID> --file -

Expectation: both commands return JSON with a new id and the given name / instructions.

Scenario 2 — providers create/update from file

Action: create a provider from a file, then patch input from a file.

cat > /tmp/provider.json <<'JSON'
{"name":"cli-file-openai","providerName":"openai","input":{"apiKey":"<api-key>"}}
JSON

./algolia agentstudio providers create --application-id <APP_ID> --file /tmp/provider.json

cat > /tmp/provider-patch.json <<'JSON'
{"input":{"apiKey":"<api-key>"}}
JSON

./algolia agentstudio providers update <provider-id> --application-id <APP_ID> --file /tmp/provider-patch.json

Expectation: create returns an id with providerName: "openai". Update exits 0. providerName is unchanged.

Scenario 3 — exclusive flags (failure mode)

Action: pass --json and --file together, then --file with --name.

./algolia agentstudio agents create --json '{"name":"x","instructions":"y"}' --file /tmp/agent.json
./algolia agentstudio agents create --file /tmp/agent.json --name x
./algolia agentstudio providers create --json '{"name":"x"}' --file /tmp/provider.json

Expectation: each command errors. --json cannot be combined with --file. --json and --file cannot be combined with --name (or --instructions on agents).

⚠️ Dependencies

• Stacked on #290 (lw-oct-agent-studio-3).
• Target application must have Agent Studio.
• No new environment variables. JSON files may contain API keys; avoid committing real keys.

Made with Cursor

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 21 complexity · 49 duplication

Metric	Results
Complexity	21
Duplication	49

View in Codacy

_{TIP This summary will be updated as you push new changes.}

[cmarguta-alg]

Status: 🟢 pass · 🔴 fail · 🟡 inconclusive

Personal QA Agent — #291 (9af388a)

Verdict: not merge-ready for the extra requirement that a --file payload can set everything the SDK allows on that entity.

--file / -f / stdin plumbing is 🟢 (help, exclusivity, create, update). Agent files can set the full AgentConfigCreate / AgentConfigUpdate surface. Provider files cannot: ProviderInput oneOf unmarshal+marshal drops extra input fields before the HTTP call. The same drop happens with --json (pre-existing from #290, but --file inherits it).

Tested on app VUX4PAGOPD via --application-id. Dummy LLM keys only (no live provider create). QA agents deleted after; app left at 0 agents / 0 providers.

SDK field coverage (the extra check)

SDK v4.48.0 types used by the CLI:

Entity	SDK type	Fields
Agent create	AgentConfigCreate	name, description, providerId, model, instructions, systemPrompt, templateType, config, tools
Agent update	AgentConfigUpdate	same, nullable
Provider create	ProviderAuthenticationCreate	name, providerName, input
Provider input	ProviderInput oneOf	openai/anthropic/xai: apiKey+baseUrl; azure: apiKey+azureEndpoint+azureDeployment+apiVersion; openai_compatible: apiKey+baseUrl+defaultModel; google_genai/deepseek: apiKey
Provider update	ProviderAuthenticationPatch	name and/or input
Tools	ToolConfigInput	algolia_search_index, client_side, mcp_tools, algolia_recommend

Round-trip (unmarshal → marshal, same path as --file) and live API:

Payload	Status	Notes
Agent: name, description, instructions, systemPrompt, templateType, config, tools	🟢	Live: description/systemPrompt/config/templateType persisted. Tools: client_side, algolia_search_index, mcp_tools, algolia_recommend all stored
Provider openai/anthropic/xai apiKey (+ optional baseUrl)	🟢 round-trip	Live create 🟡 dummy key → API 422 Invalid API key provided. File reached the API
Provider azure_openai extra input	🔴	File/json azureEndpoint+azureDeployment+apiVersion marshal down to {"apiKey":"…"} only. Live 422 body.azureEndpoint: Field required
Provider openai_compatible defaultModel	🔴	Round-trip drops defaultModel. Live 422 body.defaultModel: Field required

Cause: generated ProviderInput.UnmarshalJSON fills several oneOf variants at once; MarshalJSON emits Anthropic first, which only has apiKey/baseUrl. --file is not a thinner DTO — it is this SDK type.

Preferred CLI fix: send the file/--json bytes as the request body instead of round-tripping through ProviderAuthenticationCreate / ProviderInput. Validation of name / providerName / input present can stay.

Results

Check	Status	Notes
task build	🟢
go test ./pkg/cmdutil ./pkg/cmd/agents/create,update ./pkg/cmd/providers/create,update -count=1	🟢
Help documents --file / -f beside --json	🟢	agents+providers create/update
Scenario 1 agents create --file	🟢	cli-file-agent id 0b3baef5-…
Scenario 1 agents create --file - (stdin)	🟢	id 353e4820-…
Scenario 2 providers create --file with dummy key	🟡	422 Invalid API key (same as #290). No live update
Scenario 3 --json + --file	🟢	--json cannot be combined with --file
Scenario 3 --file + --name	🟢	agents and providers
Missing file	🟢	reading file: open … no such file
Invalid JSON file	🟢	parsing agent JSON
Agent update --file (description, instructions, systemPrompt, config, tools)	🟢
Flag-only agent create (--name + --instructions)	🟢	still limited to those two fields; full surface is --file/--json only, as designed

Notes (not extra 🔴)

• allowUnlistedIndices: true on a search tool 422 unless mode is dynamic — API validation; CLI sent the field.
• MCP transport: "sse" 422; accepted streamable_http.
• Recommend tool without modelName: SDK injects "" and API 422. With modelName: "related-products" it stored.
• --json has the same azure / openai_compatible drop (confirmed live).

— Personal QA Agent