Improve README.md for users and AI agents

[patrikbraborec]

Summary

README.md is important both for users and agents. It should be comprehensive, well-structured, and serve as a good entry point for both audiences.

Action Items

• Review and improve README.md content and structure
• Ensure README serves as a good reference for AI agents consuming CLI documentation

[patrikbraborec]

Research: popular CLI READMEs

I reviewed READMEs from Stripe CLI, GitHub CLI (gh), Vercel CLI, Firebase CLI, Fly.io CLI (flyctl), and Railway CLI to identify what works.

Common patterns across top CLIs

Pattern	Stripe	GitHub	Vercel	Firebase	Fly.io	Railway
Badges (version + CI)	✅	❌	❌	✅	❌	✅
One-line description	✅	✅	✅	✅	✅	✅
Feature bullet list	✅	❌	❌	✅	❌	✅
Visual (GIF/screenshot)	GIF	Screenshot	Logo	❌	❌	❌
Installation per OS	✅	✅	❌	Partial	✅	✅
Command reference	Linked list	Defers to docs	❌	Full tables	❌	Defers
Quick Start (2-3 steps)	❌	❌	❌	❌	✅	Link only
Documentation links	✅	✅	✅	✅	❌	✅
Contributing section	✅	✅	✅	❌	✅	✅
Telemetry transparency	✅	❌	❌	❌	❌	❌
Feedback/Support section	✅	❌	❌	❌	❌	✅

What stood out

1. Stripe CLI has an animated GIF demo, clean feature bullets, per-platform installation, commands linked to docs, and a telemetry section
2. GitHub CLI defers almost everything to docs and puts Documentation before Installation
3. Firebase CLI includes full categorized command tables, auth methods, CI/proxy guidance
4. Railway CLI strikes a good balance between clean overview, wide install options, and linking out for details

---

Proposed new README structure

This structure should also work well for AI agents consuming CLI docs (explicit command names, scannable sections, structured data over prose).

# Apify CLI

[badges: npm version, CI status]

One-line description: what it is + what it does.

## Features

- Create, develop, and deploy Apify Actors from your terminal
- Manage Actors, datasets, key-value stores, and request queues
- Run Actors locally for development and testing
- Push projects to the Apify cloud platform
- Works with any programming language (via Docker)

## Quick start

3-step numbered quickstart:
1. Install
2. Login
3. Create + run your first Actor

(Concrete commands, copy-pasteable. This is the most important section
for both humans and AI agents.)

## Installation

### macOS / Linux (recommended)
### macOS / Linux (Homebrew)
### Windows
### NPM (cross-platform)

(Keep it clean and per-platform. Move the verbose fnm/npx tangents
to a note or FAQ.)

## Commands

Brief categorized overview (not the full reference, but enough for
quick scanning):

| Command | Description |
|---------|-------------|
| `apify create` | Create a new Actor project from a template |
| `apify init` | Initialize an existing project as an Actor |
| `apify run` | Run Actor locally |
| `apify login` | Authenticate with Apify platform |
| `apify push` | Deploy Actor to the Apify cloud |
| `apify call` | Run Actor on the Apify cloud |
| `apify pull` | Pull Actor from the cloud to local |
| `apify builds` | Manage Actor builds |
| `apify secrets` | Manage secret environment variables |
| ... | ... |

→ Full command reference: docs.apify.com/cli/docs/reference

## Documentation

Links to:
- Full CLI docs
- Actor development guide
- Apify Platform docs

## Telemetry

What data is collected, how to opt out. Only Stripe does this among
the CLIs I reviewed, but users notice and appreciate it.

## Contributing

Link to CONTRIBUTING.md.

## Feedback & support

- Report bugs (GitHub issues link)
- Apify Help Center
- Contact us

## License

Apache-2.0

---

What changes from the current README

Current	Proposed	Why
No feature list	Features section with bullet points	Gives users (and AI agents) an immediate sense of what the CLI does
No quick start	Quick start (3 steps)	Every popular CLI hooks users fast; agents also need a clear default workflow
Very verbose "Basic usage" with long explanations	Concise command table + link to full docs	Scannable for humans and parseable for agents
.actor/actor.json deep dive in README	Move to dedicated docs page, link from README	README should be an entry point, not a reference manual
Environment variables section	Move to docs, link from README	Same reason
No telemetry section	Add telemetry section	Only Stripe does this, but it's good practice and users look for it
"Need help?" buried at end	Dedicated feedback & support section	Stripe and Railway both do this
No contributing section	Add contributing link	5 of 6 CLIs have this

Why this helps AI agents

• A features section gives agents an explicit capability list to match against user intent
• A command table is structured and parseable, unlike prose descriptions
• A quick start section gives agents a default workflow to recommend
• Clear section headers make extraction straightforward
• Tables and bullets are easier to parse than long paragraphs

[patrikbraborec]

Suggestions for other docs updates alongside the README rewrite

Since the README is getting reworked, it makes sense to update the surrounding files too. Here's what I found looking at the current state of contribution docs.

---

1. CONTRIBUTING.md needs a refresh

The current file is thin and partially outdated (it still says to manually increment package.json version, but releases are automated via GitHub Actions now). Specific gaps:

• No prerequisites listed. Contributors need to know about Node.js 20+, Yarn, and optionally Bun (for bundle builds) before they start.
• No local setup steps. The file jumps straight to yarn dev:apify without explaining git clone → yarn install → yarn build first.
• No mention of code style tooling. The project uses Biome (JS/TS formatting), ESLint (linting), and Prettier (Markdown/YAML). The pre-commit hook catches violations, but contributors shouldn't have to discover this by failing a hook.
• No PR guidelines. Nothing about branch naming, commit message conventions, or what reviewers expect.
• The publish section should be rewritten to match the actual release process (automated via pre_release.yaml and release.yaml).
• No explanation of test categories. Contributors don't know when to run test:local vs test:api vs test:python vs test:cucumber.

2. Add a CLAUDE.md file

There's no CLAUDE.md at the repo root. Since the issue specifically calls out AI agents, this is a natural addition. It would cover project overview (TypeScript CLI built with oclif), key directories (src/commands/, src/lib/, test/, features/), build/test/lint commands, and common patterns like the useAuthSetup/useTempPath test hooks.

3. Add GitHub issue and PR templates

The .github/ directory has no issue templates or PR template. A PR template with a basic checklist (tests pass, linted, description of changes) and separate issue templates for bugs vs feature requests would save reviewers time.

4. Add a CODE_OF_CONDUCT.md

5 of 6 CLIs in the research have one. A standard Contributor Covenant file takes five minutes.

5. CODEOWNERS could be more granular

Currently only two owners: @vladfrangu for everything, @TC-MO for docs. If the team grows, splitting ownership by directory (test/, features/, .github/workflows/) would route PRs to the right people faster.

6. .editorconfig has a minor inconsistency

TypeScript/JavaScript is set to tab indentation, which matches biome.json. But the default for all files is 4 spaces, which could confuse contributors editing non-TS files. Worth a quick check that this matches what the project actually uses.

---

Priority

Priority	Item	Effort
High	Refresh CONTRIBUTING.md	Medium
High	Add CLAUDE.md	Low-medium
Medium	Add PR template	Low
Medium	Add issue templates	Low
Low	Add CODE_OF_CONDUCT.md	Trivial
Low	Expand CODEOWNERS	Trivial
Low	Audit .editorconfig	Trivial

[patrikbraborec]

Add to CLAUDE.md info that before each push, it should run lints, build, etc.