Agent DX: three help strings route agents to the wrong tool

[l2ysho]

Summary

Driving apify from a coding agent to scaffold and deploy a new Actor, I lost three separate cycles — each time because a help string pointed at the wrong tool. The commands I needed all exist. Fixing three strings would have removed the friction entirely.

Version: apify-cli/1.10.0 (d227b1f), darwin-arm64, node 24.18.0.

1. --template help sends you to a raw GitHub URL instead of templates ls

apify create --help currently says:

-t, --template=<value> Template for the Actor. If not provided, the command will prompt for it. Visit https://raw.githubusercontent.com/apify/actor-templates/master/templates/manifest.json to find available template names.

Followed literally, so I fetched and parsed 38 KB of JSON over HTTP to enumerate templates — when apify templates ls --json was right there and returns exactly what I needed.

This matters more for agents than humans: a human skims the command list and spots templates; an agent reads the flag help for the command it is already running and does what it says.

Fix: point at the local command.

-t, --template=<value>  Template for the Actor. If not provided, the command will
                        prompt for it. Run "apify templates ls --json" to list
                        available templates.

The same raw-manifest URL also appears in apify help --skill, under Develop and deploy a local Actor, so it reproduces there too.

2. Auth help describes a token location that is wrong under the keyring backend

apify login --help and apify auth login --help both say:

Authenticates your Apify account and saves credentials to '~/.apify/auth.json'.

On this machine secretsBackend is keyring, and ~/.apify/auth.json holds no token at all:

$ python3 -c "import json;print(list(json.load(open('$HOME/.apify/auth.json')).keys()))"
['id', 'username', 'profile', 'email', 'proxy', 'plan',
 'effectivePlatformFeatures', 'createdAt', 'isPaying', 'secretsBackend']

I read the file, found no token, and concluded the credential was unreachable from a script — so I wrote a fallback that shells out to apify api users/me and parses the response. apify auth token does exactly what I needed and I never looked for it, because the help had already told me where the token lived.

This one is the most costly of the three: it does not merely fail to help, it produces a confident and wrong mental model.

Fix: make the help backend-aware, or drop the path and say where to get the token:

Authenticates your Apify account and stores the credentials
(location depends on the secrets backend — print the token with "apify auth token").

3. apify help --skill is effectively undiscoverable

The skill content is good — --json on list/info commands, apify create --json returning { dir, actorJsonPath, template, postCreate, … } with stdout kept clean for jq, apify runs wait, the non-interactive flag list. It is close to exactly what an agent needs.

I never ran it. It is the second-to-last line of apify help, below the docs link and the support link, and nothing surfaces it where an agent is actually working:

• not in apify -h's header
• not in apify create's output or nextSteps
• not in the AGENTS.md generated into every new project — which ships its own hand-written Commands section duplicating much of the same ground, without ever mentioning apify help --skill

Fix, cheapest first:

1. Add a line to the generated AGENTS.md: "Run apify help --skill for CLI usage patterns." This puts it in front of every agent working in a scaffolded project.
2. Mention it in apify create --json's nextSteps.
3. Move it above the docs/support links in apify help.

Why these three together

They are one class of bug — help text that routes the reader away from the tool that solves their problem — and one PR fixes all of them. The commands are already correct; only the signposting is off.

Happy to open a PR if useful.

---

Related — agent friction found in the same session

These came out of one attempt to scaffold, configure and deploy a new Actor by driving the CLI from a coding agent. Filing this issue as the hub; each of the others stands on its own.

• apify create assumes a greenfield standalone repo — no monorepo or existing-repo path #1425 — apify create assumes a greenfield standalone repo (no monorepo path, --source github can't target a subdirectory, nested git repo by default)
• apify create reports Success without validating the scaffold can run #1426 — apify create reports Success without validating the scaffold can run (no engines.node check, npm warn allow-scripts passed through uninterpreted)
• Add apify proxy check — verify proxy reachability against a real target #1427 — Add apify proxy check to verify proxy reachability against a real target
• No CLI surface for git integrations — --source github dead-ends on an unconnected workspace #1428 — No CLI surface for git integrations; --source github dead-ends on an unconnected workspace

The common thread across all five: the CLI usually has the capability, but an agent can't find it, can't reach it non-interactively, or is told something that isn't true. Only #1427 asks for genuinely new functionality.

[l2ysho]

Correction on scope: the third fix I suggested — adding a apify help --skill pointer to the generated AGENTS.md — belongs in apify/actor-templates, which owns that file. Moved to apify/actor-templates#941 (section 4).

The other two points in this issue are CLI-side and stand as written: the --template flag help pointing at the raw manifest URL instead of apify templates ls --json, and the auth help naming ~/.apify/auth.json as the token location when the keyring backend is in use.