Skip to content

contacts.md

Latest commit

 

History

History
121 lines (90 loc) · 3.8 KB

contacts.md

File metadata and controls

121 lines (90 loc) · 3.8 KB
Raw

Contacts Commands

Search for people and manage contact aliases.

Every contacts command accepts global options (--account, --as, --format, --json, --output, --verbose).

contacts search <query>

Search contacts, the Global Address List (GAL), and people you've interacted with via Microsoft Graph's People API. Results are ranked by relevance — people you email frequently appear first.

outlook-cli contacts search "Alice"
outlook-cli contacts search "alice@example.com"
outlook-cli contacts search "engineering" --top 20
outlook-cli contacts search "Alice" --json
Option Description Default
--top <n> Maximum number of results. The People API returns at most 1000 results. 10
--input <file> Load options from a JSON file. —

Example output (text):

Name                           Email                          Company
────────────────────────────────────────────────────────────────────────────
Alice Johnson                  alice@example.com              Contoso Ltd
Alice Williams                 alice.w@example.com            Fabrikam Inc

Example output (JSON):

[
  {
    "displayName": "Alice Johnson",
    "emailAddresses": [
      { "address": "alice@example.com", "rank": 1 }
    ],
    "companyName": "Contoso Ltd",
    "department": "Engineering"
  }
]

Search scope: Personal Microsoft accounts search contacts only. Work/school (Entra ID) accounts also search the organization's Global Address List (GAL), which includes everyone in the directory. Bridge accounts search the GAL via Outlook COM CreateRecipient+Resolve (alias resolution) and GAL AddressEntries iteration (multi-result), merging results with personal contacts and deduplicating by SMTP email.

Bridge GAL search returns additional fields: source ("gal" or "personal"), alias (email prefix), department, and companyName extracted from MAPI properties.

# Search by alias — finds "Mike Hillberg" from "mikehill"
outlook-cli contacts search mikehill --account bridge

# Search by display name
outlook-cli contacts search "Mike Hillberg" --account bridge --json

Contact Aliases

Aliases let you create short nicknames for email addresses you use frequently. Once set, you can use the alias anywhere an email address is accepted:

# Set up an alias
outlook-cli contacts alias set boss jane.smith@contoso.com

# Now use it in any command
outlook-cli mail draft --to boss --subject "Update" --body "Done!" --yes
outlook-cli mail search "from:boss"

Aliases are stored in ~/.outlook-cli/aliases.json. Both Node.js and C# implementations read the same file.

contacts alias set <name> <email>

Create or update a contact alias. If the alias already exists, it's overwritten with the new email.

outlook-cli contacts alias set fred freddie@outlook.com
outlook-cli contacts alias set boss jane.smith@contoso.com
outlook-cli contacts alias set team-lead alice@example.com

Arguments:

  • <name> — The alias name (short, no spaces). Used in --to, --cc, etc.
  • <email> — The full email address the alias maps to.

contacts alias remove <name>

Remove a contact alias.

outlook-cli contacts alias remove fred

contacts alias list

List all configured aliases.

outlook-cli contacts alias list
outlook-cli contacts alias list --json

Example output (text):

fred    freddie@outlook.com
boss    jane.smith@contoso.com
wilma   wilma@outlook.com

Example output (JSON):

{
  "fred": "freddie@outlook.com",
  "boss": "jane.smith@contoso.com",
  "wilma": "wilma@outlook.com"
}