docs(cli): compare airbyte-cli conventions for PyAirbyte

[Aaron ("AJ") Steers (aaronsteers)]

This PR targets the following PR:

• feat(cli): add airbyte-cloud and airbyte-local CLIs #1010

---

Summary

AJ asked for this comparison before applying PyAirbyte CLI behavior changes. This stacked draft PR adds a docs-only proposal comparing PR 1010's PyAirbyte CLI shape against the separate airbytehq/airbyte-cli codebase.

No CLI behavior changes are implemented here; code changes are intentionally deferred pending AJ approval of the naming and ergonomics decisions.

The proposal covers:

• get vs describe naming
• command grouping and noun/verb order
• login/logout and credential file expectations
• positional IDs vs named ID args
• JSON input/output conventions
• public/config API root and self-managed flag naming
• sync/job wait ergonomics
• help text, flag style, and schema/introspection conventions

Review & Testing Checklist for Human

• Confirm the decision matrix captures the airbyte-cli precedents AJ wants applied to PyAirbyte.
• Choose the preferred path for the highest-impact decisions: get vs describe, universal --json, credential-file compatibility, output envelopes/--fields, and self-managed root flag naming.
• Confirm no behavior changes should be implemented until a follow-up PR after approval.

Notes

Validation is intentionally lightweight because this PR adds only a Markdown proposal. I will run a git diff/status sanity check and skip Python lint unless Python files are touched.

---

Devin session

Requested by: Aaron ("AJ") Steers (@aaronsteers)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1779160319-cli-conventions-proposal' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1779160319-cli-conventions-proposal'

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

• /fix-pr - Fixes most formatting and linting issues
• /uv-lock - Updates uv.lock file
• /test-pr - Runs tests with the updated PyAirbyte
• /prerelease - Builds and publishes a prerelease version to PyPI

📚 Show Repo Guidance

Helpful Resources

• PyAirbyte Documentation
• API Reference

Community Support

Questions? Join the #pyairbyte channel in our Slack workspace.

📝 Edit this welcome message.

[github-actions]

PyTest Results (Fast Tests Only, No Creds)

85 tests  ±0   84 ✅ ±0   25s ⏱️ -6s
 1 suites ±0    0 💤 ±0 
 1 files   ±0    1 ❌ ±0 

For more details on these failures, see this check.

Results for commit b6b8185. ± Comparison against base commit 4e2973b.