Skip to content

docs(sdks/python-cli): add Portuguese quickstart guide (#13363) - #13364

Open
CreamPle wants to merge 3 commits into
BasedHardware:mainfrom
CreamPle:docs/portuguese-quickstart
Open

docs(sdks/python-cli): add Portuguese quickstart guide (#13363)#13364
CreamPle wants to merge 3 commits into
BasedHardware:mainfrom
CreamPle:docs/portuguese-quickstart

Conversation

@CreamPle

@CreamPle CreamPle commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Resolves #13363.

Adds a comprehensive, idiomatic Portuguese quickstart guide (sdks/python-cli/examples/quickstart.pt.md) for omi-cli:

  • Package name (omi-cli) vs binary executable (omi)
  • Installation options via pipx (isolated environment) and pip
  • Complete authentication walkthrough:
    • Interactive browser login (omi auth login --browser)
    • Headless API-key login (omi auth login --api-key) and environment variable (OMI_API_KEY)
    • Offline status inspection (omi auth status) vs live server verification (omi auth whoami)
  • Primary resource workflows for memories, conversations, action items, and goals
  • Structured automation guidelines with global --json option and jq recipes
  • Detailed exit codes reference table (0, 1, 2, 3, 4, 5)
  • Cross-platform shell snippets for Linux/macOS (Bash/Zsh) and Windows (PowerShell with $LASTEXITCODE validation)
  • Local Omi Desktop API integration (omi local configure, omi local search-screen)
  • Multi-environment profile management (--profile, ~/.omi/config.toml)
  • Security recommendations for credentials and shell history
  • Discovery links added in sdks/python-cli/README.md and sdks/python-cli/examples/README.md

Failure-Class: none

Review in cubic

…#13363)

Add comprehensive Portuguese quickstart guide (examples/quickstart.pt.md) covering installation, authentication (browser and API key), core resources (memories, conversations, action items, goals), automation with --json, standardized exit codes, shell syntax for Bash, Zsh, and PowerShell (including \ handling), local Desktop API, profile management, and security best practices. Links added to README discovery sections.

Failure-Class: none

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 3 files

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread sdks/python-cli/examples/quickstart.pt.md
Comment thread sdks/python-cli/examples/quickstart.pt.md
Comment thread sdks/python-cli/examples/quickstart.pt.md
Comment thread sdks/python-cli/examples/quickstart.pt.md Outdated
Comment thread sdks/python-cli/examples/quickstart.pt.md Outdated
Comment thread sdks/python-cli/examples/quickstart.pt.md Outdated
Comment thread sdks/python-cli/examples/quickstart.pt.md Outdated
…dence, and Click exit codes in Portuguese guide

Failure-Class: none
@Git-on-my-level

Copy link
Copy Markdown
Collaborator

Thanks @CreamPle — I verified this guide against the CLI implementation at the PR head and it is accurate throughout, and all seven inline notes from the earlier automated review run are addressed on this head.

sdks/python-cli/examples/quickstart.pt.md — spot-checked every claim against code:

  • The exit-code table (0–5) mirrors the stable contract in omi_cli/errors.py (EXIT_OKEXIT_NOT_FOUND), including the nuance that Click's own parser errors (missing args, unknown options) exit with 2 while application validation errors exit 1.
  • The --json placement rule (global option, before the subcommand) matches the root-level callback option in omi_cli/main.py.
  • memory create --category workwork is a valid MemoryCategory in omi_cli/models.py; conversation get <ID> --include-transcript, action-item list --open / action-item complete, and goal create --type numeric --target 2 --unit liters (unit requires a metric option) all match their command signatures in omi_cli/commands/.
  • Auth section matches omi_cli/commands/auth.py: the interactive picker (1 Browser / 2 API key), --browser, --provider apple, --api-key, offline auth status (expiry surfaced for OAuth profiles only) vs live auth whoami.
  • The precedence note — if the active profile already has a saved key, OMI_API_KEY is ignored until omi auth logout — matches the env fallback in AppContext.get_profile() (omi_cli/main.py), and the logout section correctly tells users to unset OMI_API_KEY as well. Both are easy-to-get-wrong details; good to see them documented.
  • Local Desktop section matches omi_cli/commands/local.py (configure --url/--token, status, search-screen --days/--app), and profiles persisted at ~/.omi/config.toml match omi_cli/config.py.

sdks/python-cli/README.md and sdks/python-cli/examples/README.md — both discovery links use correct relative paths and formatting consistent with the existing Japanese guide entries.

Checks note: the three failing Python jobs all fail on tests/test_auth_api_key.py::test_transport_failure_during_login_leaves_saved_config_unchanged, which fails identically on current main — this PR touches no Python, so that failure is pre-existing and not caused by this change.

Two non-blocking notes:

  1. As with the Japanese guide, a translated quickstart can drift as the CLI evolves — the "English README is the source of truth" convention applies here too.
  2. The bounty proposal in [Bounty proposal] Portuguese quickstart for omi-cli ($25 proposed) #13363 is still awaiting maintainer confirmation — worth settling there before merge.

No blocking issues from my side; leaving formal approval to a human maintainer.


by AI on behalf of David — if you need David’s attention urgently, please @Git-on-my-level and escalate with need human response.

@Git-on-my-level Git-on-my-level added docs-tooling Layer: Documentation, examples, dev tools positive-signal Automation verified a genuine fix/quality contribution labels Sep 10, 2026

@kodjima33 kodjima33 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-only i18n addition (Portuguese quickstart), same template family verified against CLI source. Not merging: hard-floor CI gate (Linux/Windows Python matrix red, pre-existing/unrelated to docs).

Resolve discovery link conflicts in sdks/python-cli/README.md and examples/README.md
@Git-on-my-level Git-on-my-level added the i18n Internationalization / localization changes label Sep 11, 2026
@Git-on-my-level

Copy link
Copy Markdown
Collaborator

Status update after the rebase onto main (e020afd), since the head moved after approval:

  • sdks/python-cli/examples/quickstart.pt.md — byte-identical to the version approved on 7cbef8a, so the earlier per-claim verification against the CLI source still stands as-is.
  • sdks/python-cli/README.md — the localized-guides line now lists all three languages; the Spanish entry arrived from main via docs(python-cli): add Spanish CLI quickstart and discovery link #13408 and merged cleanly alongside this PR's Portuguese link.
  • sdks/python-cli/examples/README.md — same clean merge: the quickstart.pt.md entry sits next to the new quickstart.es.md entry with consistent formatting.

Checks: the Python matrix (Linux 3.10/3.12, Windows ACL) is green at this head — the previously failing test_transport_failure_during_login_leaves_saved_config_unchanged was fixed on main in #13436, which clears the CI hard-floor noted at approval time.

Thanks again @CreamPle — the merge was clean and nothing needed re-review. The only open item before merge is the bounty confirmation in #13363.


by AI on behalf of David

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-tooling Layer: Documentation, examples, dev tools i18n Internationalization / localization changes positive-signal Automation verified a genuine fix/quality contribution

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bounty proposal] Portuguese quickstart for omi-cli ($25 proposed)

3 participants