Back to Details

pp-apartments

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Apartments.com — Printing Press CLI

Apartments.com — Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the 
apartments-pp-cli
binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
  1. Install via the Printing Press installer:
    bash
    npx -y @mvanhorn/printing-press install apartments --cli-only
  2. Verify: 
    apartments-pp-cli --version
  3. Ensure 
    $GOPATH/bin
    (or 
    $HOME/go/bin
    ) is on 
    $PATH
    .
If the 
npx
install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):
bash
go install github.com/mvanhorn/printing-press-library/library/other/apartments/cmd/apartments-pp-cli@latest
If 
--version
reports "command not found" after install, the install step did not put the binary on 
$PATH
. Do not proceed with skill commands until verification succeeds.
本技能驱动
apartments-pp-cli
二进制文件。在调用本技能的任何命令之前，您必须确认CLI已安装。如果未安装，请先执行以下步骤：
  1. 通过Printing Press安装器安装：
    bash
    npx -y @mvanhorn/printing-press install apartments --cli-only
  2. 验证安装：
    apartments-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
如果
npx
安装失败（比如没有Node环境、离线等），可以改用Go直接安装（需要Go 1.23及以上版本）：
bash
go install github.com/mvanhorn/printing-press-library/library/other/apartments/cmd/apartments-pp-cli@latest
如果安装后执行
--version
提示"command not found"，说明安装程序未将二进制文件添加到
$PATH
中。在验证成功之前，请不要执行技能命令。

When to Use This CLI

何时使用本CLI

Use this CLI when an agent or human needs structured Apartments.com data and needs the workflows the website itself doesn't expose: cross-search diffs over time, $/sqft and total-cost-of-occupancy rankings, multi-slug union queries, side-by-side comparison, and digest-style summaries. Reach for it for relocation tracking, value-per-dollar screens across shortlists, leasing-agent weekly digests, and any rental-search scenario that needs JSON + offline composition. Skip it for one-off browsing — the apartments.com website is fine for that.
当智能体或用户需要结构化的Apartments.com数据，且需要官网未提供的工作流时，可使用本CLI：跨时间维度的搜索差异对比、每平方英尺价格与总居住成本排名、多搜索词联合查询、并列对比，以及摘要式汇总。适用于搬迁跟踪、候选房源的性价比筛选、租赁代理每周摘要，以及任何需要JSON格式数据+离线组合的租房搜索场景。如果只是单次浏览，直接使用apartments.com官网即可，无需本CLI。

When Not to Use This CLI

何时不应使用本CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.
请勿针对需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或修改远程状态的请求激活本CLI。本CLI仅提供用于查看、导出、同步和分析的只读命令。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.
这些功能是其他同类API工具所不具备的。

Time-series intelligence

时间序列分析

  • watch
     — Re-run a stored search and surface what's NEW, REMOVED, or PRICE-CHANGED since the last sync.
    Pick this when an agent is tracking a relocation over time and needs a reproducible 'what changed since last week' digest, not a fresh search.
    bash
    apartments-pp-cli watch austin-2br --json --since 7d
  • drops
     — List listings whose max-rent dropped by ≥N% within a time window.
    Pick this when timing the market or watching for distressed listings.
    bash
    apartments-pp-cli drops --since 14d --min-pct 5 --json
  • stale
     — Flag listings whose price and availability haven't changed in N days — often phantom or stuck.
    Pick this when a listing seems too good to be true; stale ones often are.
    bash
    apartments-pp-cli stale --days 30 --json --select url,maxrent,unchanged_days
  • phantoms
     — Surface listings flagged by a three-signal join: 404 on re-fetch, dropped from saved-search results, or stale ≥45 days.
    Pick this when prepping a shortlist for tour scheduling — phantoms waste tour slots.
    bash
    apartments-pp-cli phantoms --json
  • history
     — Time-series of every observation of one listing — rent, availability, status.
    Pick this when reasoning about a single listing's price trajectory.
    bash
    apartments-pp-cli history https://www.apartments.com/example-property-1234 --json
  • watch
     — 重新执行已保存的搜索，展示自上次同步以来新增、移除或价格变动的房源。
    当智能体需要跟踪搬迁进度，且需要可复现的「自上周以来的变化」摘要而非全新搜索结果时，使用该命令。
    bash
    apartments-pp-cli watch austin-2br --json --since 7d
  • drops
     — 列出在指定时间窗口内最高租金降幅≥N%的房源。
    当需要把握市场时机或关注降价房源时，使用该命令。
    bash
    apartments-pp-cli drops --since 14d --min-pct 5 --json
  • stale
     — 标记价格和可用性连续N天未变化的房源——这类房源通常是虚假或已失效的。
    当某个房源看起来过于优惠时，使用该命令；失效房源往往存在此类特征。
    bash
    apartments-pp-cli stale --days 30 --json --select url,maxrent,unchanged_days
  • phantoms
     — 通过三重信号识别虚假房源：重新获取时返回404、从已保存搜索结果中消失、或连续≥45天无变化。
    当准备候选房源用于预约看房时，使用该命令；虚假房源会浪费看房时间。
    bash
    apartments-pp-cli phantoms --json
  • history
     — 单个房源的所有历史记录——租金、可用性、状态的时间序列数据。
    当需要分析单个房源的价格走势时，使用该命令。
    bash
    apartments-pp-cli history https://www.apartments.com/example-property-1234 --json

Cross-market joins

跨区域联合搜索

  • nearby
     — Fan out a search across multiple cities, zips, or neighborhoods and return one ranked, deduped list.
    Pick this when an agent needs a single ranked feed across multiple search slugs without writing a fan-out loop.
    bash
    apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --rank sqft --agent
  • nearby
     — 在多个城市、邮编或社区范围内展开搜索，返回一个经过排名和去重的列表。
    当智能体需要在多个搜索范围内获取统一排名的结果，而无需编写循环逻辑时，使用该命令。
    bash
    apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --rank sqft --agent

Local-store math

本地存储数据分析

  • value
     — Rank synced listings by 12-month total cost (rent + pet rent + pet deposit + pet fee), filtered to your hard budget.
    Pick this when budget is binding and pet fees might push a listing over the line.
    bash
    apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,total_cost
  • rank
     — Rank synced listings by ratio metrics — price per square foot or price per bedroom.
    Pick this when value-per-dollar is the goal, not 'best match' or 'lowest price'.
    bash
    apartments-pp-cli rank --by sqft --beds 2 --price-max 2500 --json --limit 10
  • floorplans
     — Rank per-floor-plan rent/sqft across synced listings — same building can yield 4 plans at different ratios.
    Pick this when a building has multiple floor plans and you want the cheap one specifically.
    bash
    apartments-pp-cli floorplans --rank price-per-sqft --beds 2 --json --limit 10
  • must-have
     — Filter synced listings to those whose amenities array contains ALL listed terms via FTS5.
    Pick this when the must-haves are free-text, not in apartments.com's amenity dropdown.
    bash
    apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json
  • value
     — 根据12个月总居住成本（租金+宠物租金+宠物押金+宠物费用）对已同步房源进行排名，并筛选符合预算的房源。
    当预算有限，且宠物费用可能导致房源超出预算时，使用该命令。
    bash
    apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,total_cost
  • rank
     — 根据比率指标（每平方英尺价格或每卧室价格）对已同步房源进行排名。
    当目标是性价比而非「最佳匹配」或「最低价格」时，使用该命令。
    bash
    apartments-pp-cli rank --by sqft --beds 2 --price-max 2500 --json --limit 10
  • floorplans
     — 根据每平方英尺租金对已同步房源的不同户型进行排名——同一建筑可能有4种不同性价比的户型。
    当某建筑有多种户型，且您只想寻找性价比最高的户型时，使用该命令。
    bash
    apartments-pp-cli floorplans --rank price-per-sqft --beds 2 --json --limit 10
  • must-have
     — 通过FTS5筛选出设施列表包含所有指定关键词的已同步房源。
    当您的必备设施是自由文本，且不在apartments.com的设施下拉选项中时，使用该命令。
    bash
    apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json

Shortlist workflows

候选房源工作流

  • compare
     — Pivot 2–8 listings into a wide table — one column per listing — with computed $/sqft and amenity overlap.
    Pick this when narrowing a shortlist; the wide table makes amenity-overlap deltas obvious.
    bash
    apartments-pp-cli compare austin-arboretum-1 austin-arboretum-2 austin-arboretum-3 --json
  • digest
     — Single-shot composer: new + removed + price-drops + top-5 by $/sqft + stale + phantom flags for one saved search over N days.
    Pick this when an agent needs a Monday-morning summary in one call.
    bash
    apartments-pp-cli digest --saved-search austin-2br --since 7d --format md
  • shortlist
     — Tag-based local shortlist table; add/show/remove listings with notes and tags.
    Pick this when an agent or user is curating a shortlist; downstream commands like 
    compare
    read from it.
    bash
    apartments-pp-cli shortlist add https://www.apartments.com/example-1234 --tag austin --note "liked the kitchen"
  • compare
     — 将2-8个房源转换为宽表格式——每列对应一个房源，并计算每平方英尺价格和设施重叠情况。
    当需要缩小候选房源范围时，使用该命令；宽表格式可清晰展示设施差异。
    bash
    apartments-pp-cli compare austin-arboretum-1 austin-arboretum-2 austin-arboretum-3 --json
  • digest
     — 一站式汇总工具：针对某一已保存搜索，展示指定天数内的新增、移除、降价房源，以及每平方英尺价格Top5房源、失效和虚假房源标记。
    当智能体需要一键生成周一晨间摘要时，使用该命令。
    bash
    apartments-pp-cli digest --saved-search austin-2br --since 7d --format md
  • shortlist
     — 基于标签的本地候选房源表；可添加、查看、移除房源，并添加备注和标签。
    当智能体或用户正在整理候选房源时，使用该命令；后续命令如
    compare
    可读取该表数据。
    bash
    apartments-pp-cli shortlist add https://www.apartments.com/example-1234 --tag austin --note "liked the kitchen"

Aggregations

数据聚合

  • market
     — Median, p10, p90 of rent and rent/sqft, pet-friendly share, by city/state and bed count.
    Pick this when an agent needs to anchor 'is this a fair price' against the local distribution.
    bash
    apartments-pp-cli market austin-tx --beds 2 --json
  • market
     — 按城市/州和卧室数量统计租金及每平方英尺租金的中位数、10分位数、90分位数，以及宠物友好房源占比。
    当智能体需要参考本地市场价格分布来判断某房源价格是否合理时，使用该命令。
    bash
    apartments-pp-cli market austin-tx --beds 2 --json

HTTP Transport

HTTP传输

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
本CLI使用兼容Chrome的HTTP传输协议访问面向浏览器的端点。正常API调用无需常驻浏览器进程。

Discovery Signals

发现信号

This CLI was generated with browser-observed traffic context.
  • Capture coverage: 0 API entries from 0 total network entries
  • Protocols: html-ssr (95% confidence)
  • Generation hints: use Surf with Chrome TLS fingerprint at runtime (UsesBrowserHTTPTransport), all responses are HTML/SSR — extract via html_extract mode: page, no clearance cookie capture; no resident browser sidecar, schema.org microdata (meta itemprop=streetAddress|addressLocality|addressRegion|postalCode) plus data-beds / data-baths / data-maxrent attributes are the primary extraction targets
  • Candidate command ideas: rentals — Path-slug search is the primary entry point at apartments.com; listing — Listing detail page extracts schema.org microdata
  • Caveats: protection-active: Apartments.com (CoStar) employs Akamai-style bot detection. stdlib HTTP returns 403; Surf with Chrome TLS fingerprint clears it. Watch for protection escalation that might require Chrome-clearance cookie import or full-browser fallback in future versions.
本CLI是基于浏览器捕获的流量上下文生成的：
  • 捕获覆盖范围：0个API条目（共0个网络条目）
  • 协议：html-ssr（95%置信度）
  • 生成提示：运行时使用带有Chrome TLS指纹的Surf（UsesBrowserHTTPTransport），所有响应均为HTML/SSR——通过html_extract模式提取：页面，无需捕获验证Cookie；无需常驻浏览器进程，schema.org微数据（meta itemprop=streetAddress|addressLocality|addressRegion|postalCode）以及data-beds / data-baths / data-maxrent属性是主要提取目标
  • 候选命令思路：rentals — 路径搜索词是apartments.com的主要入口；listing — 房源详情页提取schema.org微数据
  • 注意事项：反机器人保护已激活：Apartments.com（CoStar）采用Akamai风格的机器人检测。标准库HTTP请求会返回403；使用带有Chrome TLS指纹的Surf可通过检测。未来版本需注意保护机制升级，可能需要导入Chrome验证Cookie或使用完整浏览器作为备选方案。

Command Reference

命令参考

listing — Fetch a single Apartments.com listing detail page by URL or property ID, parsing rent, beds/baths, address, amenities, and pet policy.
  • apartments-pp-cli listing <property_id>
    — Fetch one Apartments.com listing detail page and parse schema.org microdata.
rentals — Search Apartments.com rental listings by city, beds, baths, price, and pet policy. Returns parsed listing placards.
  • apartments-pp-cli rentals
    — Run a path-slug search at apartments.com and return listing placards parsed from the HTML response.
Hand-written commands
  • apartments-pp-cli sync-search <saved-search>
    — Run a saved search against apartments.com and snapshot placards into the local store.
  • apartments-pp-cli watch <saved-search>
    — Diff the latest sync of a saved search against the previous; emit NEW / REMOVED / PRICE-CHANGED listings.
  • apartments-pp-cli nearby <slug...>
    — Fan out a search across multiple city/zip/neighborhood slugs and return one ranked, deduped list.
  • apartments-pp-cli value
    — Rank synced listings by 12-month total cost of occupancy (rent + pet rent + pet deposit + pet fee).
  • apartments-pp-cli rank
    — Rank synced listings by ratio metrics — $/sqft or $/bed.
  • apartments-pp-cli compare <url-or-id...>
    — Pivot 2–8 listings into a wide table — one column per listing — with computed $/sqft and amenity overlap.
  • apartments-pp-cli drops
    — List listings whose max-rent dropped by ≥N% within a time window.
  • apartments-pp-cli stale
    — Flag listings whose price and availability have not changed in N days — phantom or stuck signal.
  • apartments-pp-cli phantoms
    — Surface listings flagged by a three-signal union: 404 on re-fetch, dropped from saved-search results, or stale ≥45...
  • apartments-pp-cli market <city-state>
    — Aggregate synced listings: median, p10, p90 of rent and rent/sqft, plus pet-friendly share.
  • apartments-pp-cli history <url-or-id>
    — Time-series of every observation of one listing — rent, availability, status.
  • apartments-pp-cli digest
    — Weekly digest composer: new + removed + price-drops + top-by-sqft + stale + phantoms in one structured output.
  • apartments-pp-cli floorplans
    — Rank per-floor-plan rent/sqft across synced listings.
  • apartments-pp-cli must-have <term...>
    — Filter synced listings to those whose amenities array contains ALL listed terms via FTS5.
  • apartments-pp-cli shortlist
    — Local shortlist table — add / show / remove listings with notes and tags.
listing — 通过URL或房源ID获取单个Apartments.com房源详情页，解析租金、卧室/浴室数量、地址、设施和宠物政策。
  • apartments-pp-cli listing <property_id>
    — 获取单个Apartments.com房源详情页并解析schema.org微数据。
rentals — 按城市、卧室数量、浴室数量、价格和宠物政策搜索Apartments.com租房房源，返回解析后的房源卡片。
  • apartments-pp-cli rentals
    — 在apartments.com执行路径搜索词搜索，返回从HTML响应中解析的房源卡片。
手动编写的命令
  • apartments-pp-cli sync-search <saved-search>
    — 针对apartments.com执行已保存的搜索，并将房源卡片快照保存到本地存储。
  • apartments-pp-cli watch <saved-search>
    — 将已保存搜索的最新同步结果与上一次结果对比；输出新增/移除/价格变动的房源。
  • apartments-pp-cli nearby <slug...>
    — 在多个城市/邮编/社区搜索词范围内展开搜索，返回一个经过排名和去重的列表。
  • apartments-pp-cli value
    — 根据12个月总居住成本（租金+宠物租金+宠物押金+宠物费用）对已同步房源进行排名。
  • apartments-pp-cli rank
    — 根据比率指标（$/sqft或$/bed）对已同步房源进行排名。
  • apartments-pp-cli compare <url-or-id...>
    — 将2-8个房源转换为宽表格式——每列对应一个房源，并计算每平方英尺价格和设施重叠情况。
  • apartments-pp-cli drops
    — 列出在指定时间窗口内最高租金降幅≥N%的房源。
  • apartments-pp-cli stale
    — 标记价格和可用性连续N天未变化的房源——虚假或已失效信号。
  • apartments-pp-cli phantoms
    — 通过三重信号识别虚假房源：重新获取时返回404、从已保存搜索结果中消失、或连续≥45天无变化。
  • apartments-pp-cli market <city-state>
    — 聚合已同步房源：租金及每平方英尺租金的中位数、10分位数、90分位数，以及宠物友好房源占比。
  • apartments-pp-cli history <url-or-id>
    — 单个房源的所有历史记录——租金、可用性、状态的时间序列数据。
  • apartments-pp-cli digest
    — 每周摘要工具：一键输出新增、移除、降价房源，以及每平方英尺价格Top5房源、失效和虚假房源标记。
  • apartments-pp-cli floorplans
    — 根据每平方英尺租金对已同步房源的不同户型进行排名。
  • apartments-pp-cli must-have <term...>
    — 通过FTS5筛选出设施列表包含所有指定关键词的已同步房源。
  • apartments-pp-cli shortlist
    — 本地候选房源表——添加/查看/移除房源，并添加备注和标签。

Freshness Contract

新鲜度协议

This printed CLI owns bounded freshness only for registered store-backed read command paths. In 
--data-source auto
mode, those paths check 
sync_state
and may run a bounded refresh before reading local data. 
--data-source local
never refreshes. 
--data-source live
reads the API and does not mutate the local store. Set 
APARTMENTS_NO_AUTO_REFRESH=1
to skip the freshness hook without changing source selection.
When JSON output uses the generated provenance envelope, freshness metadata appears at 
meta.freshness
. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment.
本CLI仅对已注册的基于存储的只读命令路径保证有限的新鲜度。在
--data-source auto
模式下，这些路径会检查
sync_state
，并可能在读取本地数据前执行有限刷新。
--data-source local
模式从不刷新。
--data-source live
模式读取API且不修改本地存储。设置
APARTMENTS_NO_AUTO_REFRESH=1
可跳过新鲜度检查，无需更改数据源选择。
当JSON输出使用生成的来源信封时，新鲜度元数据会显示在
meta.freshness
字段中。将其视为对应命令路径的当前缓存新鲜度，而非完整历史回填或API特定增强的保证。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:
bash
apartments-pp-cli which "<capability in your own words>"
which
resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 
0
means at least one match; exit code 
2
means no confident match — fall back to 
--help
or use a narrower query.
当您知道要执行的操作但不确定对应命令时，可直接询问CLI：
bash
apartments-pp-cli which "<用您自己的语言描述功能>"
which
命令会将自然语言功能查询解析为CLI精选功能索引中最匹配的命令。退出码
0
表示至少有一个匹配项；退出码
2
表示无明确匹配项——此时可使用
--help
或缩小查询范围。

Recipes

使用示例

Three-neighborhood relocation hunt

三社区搬迁搜索

bash
apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --pets dog --rank sqft --json --select url,addressLocality,maxrent,sqft,price_per_sqft
Single ranked feed across three target neighborhoods, deduped by listing URL, with 
--select
keeping only the columns the agent needs.
bash
apartments-pp-cli nearby austin-tx round-rock-tx pflugerville-tx --beds 2 --price-max 2500 --pets dog --rank sqft --json --select url,addressLocality,maxrent,sqft,price_per_sqft
在三个目标社区范围内生成统一排名的房源列表，按房源URL去重，
--select
参数仅保留智能体需要的字段。

Weekly leasing-agent digest

租赁代理每周摘要

bash
apartments-pp-cli digest --saved-search client-rachel --since 7d --format md
Composes new / removed / price-drops / top-5-by-sqft / stale / phantom flags for a single client search into a markdown report ready to paste into email.
bash
apartments-pp-cli digest --saved-search client-rachel --since 7d --format md
针对单个客户的搜索，将新增、移除、降价房源，以及每平方英尺价格Top5房源、失效和虚假房源标记整合为Markdown报告，可直接粘贴到邮件中。

Total-cost screen with hard budget

总成本预算筛选

bash
apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,maxrent,pet_rent,total_cost,price_per_sqft
Ranks the synced listings by 12-month total cost (rent + pet rent + pet deposit + pet fee), filtered to under-budget rows only.
bash
apartments-pp-cli value --budget 2800 --pet dog --months 12 --json --select rank,url,maxrent,pet_rent,total_cost,price_per_sqft
根据12个月总居住成本（租金+宠物租金+宠物押金+宠物费用）对已同步房源进行排名，仅筛选符合预算的房源。

Phantom-detection sweep before tour scheduling

看房前虚假房源检测

bash
apartments-pp-cli phantoms --json --select url,reason,unchanged_days
Three-signal union — 404, dropped from saved search, stale ≥45 days. Filter your shortlist before booking tours so you don't drive across town to a leased unit.
bash
apartments-pp-cli phantoms --json --select url,reason,unchanged_days
三重信号识别——404错误、从已保存搜索结果中消失、连续≥45天无变化。在预约看房前筛选候选房源，避免驱车前往已出租的房源。

Offline FTS amenity intersect

离线FTS设施交集筛选

bash
apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json --select url,addressLocality,maxrent,amenities
Path filter for amenities apartments.com's filter dropdown doesn't expose. FTS5 AND-join over the synced amenities array.
bash
apartments-pp-cli must-have "in-unit washer" "covered parking" "dishwasher" --json --select url,addressLocality,maxrent,amenities
筛选apartments.com设施下拉选项未涵盖的设施。通过FTS5对已同步房源的设施列表执行AND联合查询。

Auth Setup

认证设置

No authentication required.
Run 
apartments-pp-cli doctor
to verify setup.
无需认证。
执行
apartments-pp-cli doctor
验证设置。

Agent Mode

Agent模式

Add 
--agent
to any command. Expands to: 
--json --compact --no-input --no-color --yes
.
  • Pipeable — JSON on stdout, errors on stderr
  • Filterable — 
    --select
    keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
    bash
    apartments-pp-cli listing example-property --agent --select id,name,status
  • Previewable — 
    --dry-run
    shows the request without sending
  • Offline-friendly — sync/search commands can use the local SQLite store when available
  • Non-interactive — never prompts, every input is a flag
  • Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests
在任何命令后添加
--agent
参数。等效于：
--json --compact --no-input --no-color --yes
。
  • 可管道传输 — 标准输出为JSON，错误信息输出到标准错误
  • 可筛选 — 
    --select
    参数保留指定字段。点路径可访问嵌套结构；数组可遍历元素。对于冗长的API，此参数对缩小上下文范围至关重要：
    bash
    apartments-pp-cli listing example-property --agent --select id,name,status
  • 可预览 — 
    --dry-run
    参数显示请求但不发送
  • 离线友好 — 同步/搜索命令可在可用时使用本地SQLite存储
  • 非交互式 — 从不提示，所有输入均通过参数传递
  • 只读 — 请勿使用本CLI执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他修改状态的请求

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
Parse 
.results
for data and 
.meta.source
to know whether it's live or local. A human-readable 
N results (live)
summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
从本地存储或API读取数据的命令会将输出包装在来源信封中：
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
解析
.results
字段获取数据，
.meta.source
字段表示数据来源是实时API还是本地存储。仅当标准输出为终端时，才会向标准错误输出人类可读的
N results (live)
摘要；管道传输/Agent模式下，标准输出仅为纯JSON。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:
apartments-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
apartments-pp-cli feedback --stdin < notes.txt
apartments-pp-cli feedback list --json --limit 10
Entries are stored locally at 
~/.apartments-pp-cli/feedback.jsonl
. They are never POSTed unless 
APARTMENTS_FEEDBACK_ENDPOINT
is set AND either 
--send
is passed or 
APARTMENTS_FEEDBACK_AUTO_SEND=true
. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当您（或智能体）发现本CLI存在问题时，可记录反馈：
apartments-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
apartments-pp-cli feedback --stdin < notes.txt
apartments-pp-cli feedback list --json --limit 10
反馈条目存储在本地
~/.apartments-pp-cli/feedback.jsonl
文件中。仅当设置了
APARTMENTS_FEEDBACK_ENDPOINT
且传递了
--send
参数或设置
APARTMENTS_FEEDBACK_AUTO_SEND=true
时，才会发送反馈。默认行为仅存储在本地。
请记录令您感到意外的内容，而非正式的错误报告。简短、具体、单行描述：这类反馈的价值最大。

Output Delivery

输出交付

Every command accepts 
--deliver <sink>
. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
SinkEffect
stdout
Default; write to stdout only
file:<path>
Atomically write output to 
<path>
(tmp + rename)
webhook:<url>
POST the output body to the URL (
application/json
or 
application/x-ndjson
when 
--compact
)
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
所有命令均支持
--deliver <sink>
参数。输出会发送到指定的接收端，同时（或替代）输出到标准输出，因此智能体无需手动管道即可路由命令结果。支持三种接收端：
接收端效果
stdout
默认；仅输出到标准输出
file:<path>
原子性地将输出写入
<path>
（先写入临时文件再重命名）
webhook:<url>
将输出主体POST到指定URL（
application/json
格式，若使用
--compact
则为
application/x-ndjson
格式）
不支持的协议会返回结构化错误，并列出支持的类型。Webhook失败会返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
apartments-pp-cli profile save briefing --json
apartments-pp-cli --profile briefing listing example-property
apartments-pp-cli profile list --json
apartments-pp-cli profile show briefing
apartments-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. 
agent-context
lists all available profiles under 
available_profiles
so introspecting agents discover them at runtime.
配置文件是一组保存的参数值，可在多次调用中复用。适用于定时任务智能体每次调用相同命令且使用相同配置的场景——即HeyGen的「Beacon」模式。
apartments-pp-cli profile save briefing --json
apartments-pp-cli --profile briefing listing example-property
apartments-pp-cli profile list --json
apartments-pp-cli profile show briefing
apartments-pp-cli profile delete briefing --yes
显式参数始终优先于配置文件值；配置文件值优先于默认值。
agent-context
会在
available_profiles
下列出所有可用配置文件，因此智能体可在运行时发现这些配置文件。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error
代码含义
0成功
2使用错误（参数错误）
3资源未找到
5API错误（上游问题）
7速率限制（等待后重试）
10配置错误

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     → show 
    apartments-pp-cli --help
    output
  2. Starts with 
    install
     → ends with 
    mcp
    → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with 
    --agent
    )
解析
$ARGUMENTS
：
  1. 为空、
    help
    或
    --help
     → 显示
    apartments-pp-cli --help
    输出
  2. 以
    install
    开头     → 以
    mcp
    结尾 → MCP安装；否则 → 参见上方前提条件
  3. 其他情况 → 直接使用（添加
    --agent
    参数执行CLI命令）

MCP Server Installation

MCP服务器安装

  1. Install the MCP server:
    bash
    go install github.com/mvanhorn/printing-press-library/library/other/apartments/cmd/apartments-pp-mcp@latest
  2. Register with Claude Code:
    bash
    claude mcp add apartments-pp-mcp -- apartments-pp-mcp
  3. Verify: 
    claude mcp list
  1. 安装MCP服务器：
    bash
    go install github.com/mvanhorn/printing-press-library/library/other/apartments/cmd/apartments-pp-mcp@latest
  2. 注册到Claude Code：
    bash
    claude mcp add apartments-pp-mcp -- apartments-pp-mcp
  3. 验证：
    claude mcp list

Direct Use

直接使用

  1. Check if installed: 
    which apartments-pp-cli
    If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the 
    --agent
    flag:
    bash
    apartments-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help: 
    apartments-pp-cli <command> --help
    .
  1. 检查是否已安装：
    which apartments-pp-cli
    若未找到，提供安装选项（参见顶部前提条件）。
  2. 将用户查询与上方独特功能和命令参考中的最佳命令匹配。
  3. 添加
    --agent
    参数执行：
    bash
    apartments-pp-cli <command> [subcommand] [args] --agent
  4. 若存在歧义，查看子命令帮助：
    apartments-pp-cli <command> --help
    。