gws-search
Google Custom Search CLI operations via gws. Use when users need to perform web searches using Google Programmable Search Engine. Triggers: google search, custom search, web search.
Best use case
gws-search is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Google Custom Search CLI operations via gws. Use when users need to perform web searches using Google Programmable Search Engine. Triggers: google search, custom search, web search.
Teams using gws-search should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/search/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How gws-search Compares
| Feature / Agent | gws-search | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Google Custom Search CLI operations via gws. Use when users need to perform web searches using Google Programmable Search Engine. Triggers: google search, custom search, web search.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Google Search (gws search) `gws search` provides CLI access to Google Programmable Search Engine (Custom Search) with structured JSON output. > **Disclaimer:** `gws` is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google. ## Dependency Check **Before executing any `gws` command**, verify the CLI is installed: ```bash gws version ``` If not found, install: `go install github.com/omriariav/workspace-cli/cmd/gws@latest` ## Authentication Requires separate API credentials beyond standard OAuth: 1. Create a Programmable Search Engine at https://programmablesearchengine.google.com/ 2. Get an API key from Google Cloud Console 3. Set `GWS_SEARCH_ENGINE_ID` and `GWS_SEARCH_API_KEY` environment variables, or add `search_engine_id` and `search_api_key` to your config file ## Quick Command Reference | Task | Command | |------|---------| | Web search | `gws search "query"` | | Limit results | `gws search "query" --max 5` | | Search a site | `gws search "query" --site example.com` | | Image search | `gws search "query" --type image` | | Paginate results | `gws search "query" --start 11` | | Override API key | `gws search "query" --api-key <key> --engine-id <id>` | ## Detailed Usage ### search — Web search ```bash gws search <query> [flags] ``` **Flags:** - `--max int` — Maximum number of results, 1-10 (default 10) - `--site string` — Restrict search to a specific site - `--type string` — Search type: `image` or empty for web - `--start int` — Start index for results pagination (default 1) - `--api-key string` — API Key (overrides config) - `--engine-id string` — Search Engine ID (overrides config) **Examples:** ```bash gws search "golang best practices" gws search "kubernetes deployment" --max 5 gws search "release notes" --site github.com gws search "logo" --type image gws search "query" --start 11 # Page 2 of results ``` ## Output Modes ```bash gws search "query" --format json # Structured JSON (default) gws search "query" --format yaml # YAML format gws search "query" --format text # Human-readable text ``` ## Tips for AI Agents - Always use `--format json` (the default) for programmatic parsing - This command uses Google's Custom Search API, not standard Google search — it requires a separate API key and search engine ID - Max 10 results per request; use `--start` to paginate - The `--site` flag is useful for searching within a specific domain - Image search (`--type image`) returns image URLs and metadata
Related Skills
gws-tasks
Google Tasks CLI operations via gws. Use when users need to manage task lists, view/create/update/delete tasks, move tasks, or clear completed. Triggers: google tasks, task list, todo, task management.
gws-slides
Google Slides CLI operations via gws. Use when users need to create, read, or edit Google Slides presentations. Triggers: slides, presentation, google slides, deck.
gws-sheets
Google Sheets CLI operations via gws. Use when users need to read, write, or manage Google Sheets spreadsheets including cell values, rows, columns, sheets, sorting, merging, formatting, and find-replace. Triggers: sheets, spreadsheet, google sheets, cells, rows, columns, formulas, formatting.
gws-keep
Google Keep CLI operations via gws. Use when users need to list, view, or create Google Keep notes. Triggers: keep, google keep, notes, sticky notes.
gws-groups
Google Groups CLI operations via gws. Use when users need to list groups or view group members. Triggers: groups, google groups, admin directory, group members.
gws-gmail
Google Gmail CLI operations via gws. Use when users need to list emails, read messages, send email, manage labels, drafts, attachments, batch operations, or trash messages. Triggers: gmail, email, inbox, send email, mail, labels, archive, trash, drafts, attachments.
gws-forms
Google Forms CLI operations via gws. Use when users need to get form metadata, retrieve form responses, create forms, or update forms. Triggers: google forms, form responses, survey, form data, create form, update form.
gws-drive
Google Drive CLI operations via gws. Use when users need to list, search, upload, download, manage files/folders, permissions, revisions, comments, shared drives, and more. Triggers: drive, files, upload, download, folders, google drive, file management, permissions, share, shared drives.
gws-docs
Google Docs CLI operations via gws. Use when users need to read, create, or edit Google Docs documents. Triggers: google docs, document, gdoc, word processing.
gws-contacts
Google Contacts CLI operations via gws. Use when users need to list, search, view, create, or delete contacts. Triggers: contacts, google contacts, people api, contact management.
gws-chat
Google Chat CLI operations via gws. Use when users need to list/create/manage chat spaces, read/send messages, manage members, track read state, handle attachments, or monitor space events. Triggers: google chat, gchat, chat spaces, chat messages.
gws-calendar
Google Calendar CLI operations via gws. Use when users need to list calendars, view events, create/update/delete events, RSVP to invitations, manage calendar CRUD, subscriptions, ACL, free/busy queries, colors, and settings. Triggers: calendar, events, meetings, schedule, rsvp, invite, share, freebusy.