cli-spec.md

Offline command specifications

tv spec is available in v0.33.0 and later. It describes the running binary without Desktop, credentials or provider access. It does not validate a proposed invocation or claim that the provider is currently available.

tv spec
tv spec mcp alert history
tv spec chart

The first form returns a compact-purpose index of public command paths and their short descriptions, excluding duplicate autogenerated help routes. A command path returns only that command's detail and direct subcommand names. Use paths without flags or argument values. Unknown paths use the existing validation-error envelope on stderr with a nonzero exit. Successful JSON uses the normal stdout success envelope, command spec, and a data object with contract_version: cli_spec.v1 and binary_version (including build identity).

Contract and limits

• command contains canonical path segments; commands is present for the index.
• Detail includes description, command aliases, subcommands and arguments.
• Argument metadata comes from clap: id, long/short flags and aliases, positional index, required/global flags, action, recognized parser type, value names, arity, delimiter, defaults, choices, conflicts and description. Defaults are strings as declared by clap. Arity maximum null means unbounded. A type of null means an unclassified parser, not unconstrained input. Empty choices do not mean that every value is valid.
• coverage.syntax is clap_metadata; coverage.validation is partial. Conditional requirements and adapter checks are not fully represented. Read the command description and skill guidance for remaining conditions.
• coverage.semantics is documented for the annotated command paths described below, including official technical snapshots. Inspect the running binary's coverage field for the selected path; unannotated paths report unavailable. semantics: null means not annotated, never no side effects. More commands can acquire annotations without changing how they execute.
• Documented read semantics contain source, prerequisites, account/provider effects, output contract, static constraints, dynamic discovery instructions and argv examples. The default read deadline and cap reuse execution constants. Authenticated reads can refresh local credentials; account_mutation: false does not promise zero local state changes.
• Dynamic account IDs or symbols are not fetched by specification lookup. Symbol discovery points to tv mcp search <query> and data.symbols[].symbol in its output. Placeholders require caller input; examples do not prove access, data availability or scope authorization.

Before: inspect nested help and interpret prose to assemble a history request. After: read tv spec mcp alert history, choose a symbol from the indicated search result when necessary, then invoke history under the user's authority. This reduces guessing; it does not guarantee fewer tokens than short help. The index may be larger than root help because it includes nested commands.

tv schema exports the supported output schemas described below. tv validate checks candidate argv without executing it, as described below. Existing tv discover remains a Desktop-backed API diagnostic and is unrelated to offline specification lookup.

Output schemas

In v0.34.0 and later, tv schema lists supported paths; tv schema values and tv schema mcp bars export their JSON Schema 2020-12 descriptions without connecting to Desktop or MCP. Successful output uses the normal envelope with command schema and data.contract_version=cli_schema.v1; binary_version identifies the build. The index has commands as path arrays. Details have canonical command, coverage=documented_fields, unchecked, and the schema in data.schema.

Validate the actual success or error envelope against data.schema, not the schema command's wrapper. Schemas preserve legitimate nulls, empty/short bar results, unknown study identity and arbitrary dynamic study values. Additional object properties are allowed. Error details and runtime meaning are not fully specified. Structural conformance does not prove series meaning, freshness, complete history or consistency between counts and arrays. Date formats are annotations, not a market-time guarantee. References are local to the document.

Unknown paths fail with unknown_command; known unsupported paths fail with unsupported_command in cli_schema.v1 error details (validation exit 1). Outer --target-id is rejected as unsupported_target. No existing values or MCP output format changes, and schemas are descriptions for the current binary, not a new version marker inside unversioned command output.

Offline invocation validation

In v0.34.0 and later, pass argv after a required separator, without an executable name:

tv validate -- values
tv validate -- --target-id example-target values
tv validate -- mcp bars NASDAQ:EXAMPLE --timeframe 1D --count 20

Only values and mcp bars have local validation support initially. The real clap parser checks syntax; MCP bars reuse execution's request preparation, Desktop-target rejection and deadline rules. Values have no command-specific arguments. Target existence, environment configuration, credentials, provider availability and data quality remain unchecked. Validation neither executes the candidate nor reads its files, and does not initialize tracing or accounts. It is optional preparation, not permission to perform the operation.

Success uses command validate, data.contract_version=cli_validate.v1, the canonical command path, status valid and checks syntax/local_constraints passed, runtime not_checked. Input values are not echoed. Errors use stderr, exit 1, kind validation and cli_validate.v1 details with nullable command/field:

Outcome	status / code	checks.syntax / local_constraints
Invalid syntax, empty input or missing separator	invalid / invalid_syntax	failed / not_checked
Invalid local request	invalid / invalid_request or unsupported_capability	passed / failed
Known command without local support	unsupported / unsupported_command	passed / not_checked
Candidate help/version or spec/schema/validate	unsupported / non_executable_request	passed or not_checked / not_checked
Target option on the outer validate invocation	invalid / unsupported_target	not_checked / not_checked

Runtime is always not_checked. For example, count 5001 fails locally with field count; a syntactically valid data equity invocation is unsupported, not approved for execution. Use target options inside candidate argv. Keep credentials, account IDs and file contents out of shared examples; diagnostics omit candidate values and raw clap messages. Existing commands retain their normal errors and execution ordering; this tool adds no retry or source fallback.

Qualified MCP read details

Path after tv spec	Constraints and next-step guidance
mcp search	Query tokens are joined with spaces; the UTF-8 byte limit and allowed --type values come from request validation. Results remain candidates.
mcp columns	Market choices and group/search byte limits; overview without group/search, detail otherwise. Group discovery uses data.groups[].group.
mcp symbol	Qualified symbol syntax, unique column names, per-name byte limit and the actual default column set. Discover columns via data.columns[].name from a detail query.
mcp symbols	The same field constraints plus 1–50 unique symbols; ordered returned/missing/unreported outcomes. No automatic chunking.
mcp bars	Actual timeframe list, count bounds and unsupported date-range inputs. Count satisfaction does not establish calendar coverage or legacy-source equivalence.
mcp alert history	Shared symbol syntax, history bounds, timeout and symbol discovery. Coverage and notification delivery remain unconfirmed.

max_bytes counts UTF-8 bytes, not characters. nonblank rejects whitespace-only text and control_characters: false rejects control characters. Symbol patterns are ASCII and case-preserving; duplicate checks compare exact strings. Column names must be unique; omitted columns resolve to default_when_empty, not all available fields. These annotations describe client checks, not provider field availability. Default argument values remain in clap-derived arguments.

Search receipt time is not market-data time. Single-symbol identity may remain unconfirmed; batch missing and unreported outcomes have different meanings. Absent fields and explicit nulls are not interchangeable or zero. limits records these distinctions. All six operations can update local authorization through token refresh without mutating account watchlists or alerts.

Account mutation details

tv spec mcp watchlist create|update|add|remove|delete and tv spec mcp alert create|update|stop|restart|delete describe changes; looking up those specifications never dispatches them. Choose one action per invocation.

Each detail includes ID discovery, examples with synthetic targets, shared input bounds and the output/error contracts. Names use Unicode scalar counts, unlike the byte limits on market-data queries. Watchlist IDs are canonical unsigned decimal strings; alert IDs are positive integers bounded by the existing signed-64-bit provider limit. --timeout is unsupported for mutations.

Watchlist add moves existing members to the end. Update preserves omitted fields, while an explicitly empty description clears it. Alert update reactivates an inactive alert even if only its name changes. Alert restart uses existing conditions and notification settings; delete also removes fire history. Create defaults notifications and auto-deactivation to false. Specs expose these effects so an agent can check them against the user's requested operation.

readback describes the CLI's automatic follow-up and a separate read command. A usable reply and identifiable target are needed before that follow-up can run. response_received does not prove persistence; inspect the readback status and per-target observations. An item absent from an incomplete list is not a confirmed deletion. After outcome_unknown, inspect state before considering another mutation. For an uncertain create, do not select by name or create a replacement automatically. Examples are instructions for syntax, not permission to change an account.

Conditional Desktop operations

Desktop semantics cover symbol, timeframe, type, range, info, state, readiness and tab list. variants describes argument-dependent behavior; tv spec does not accept an invocation's values or select a variant for you. Each when uses clap argument IDs: present, absent, or exactly_one_present; lifecycle paths also use flag_true, flag_false and runtime observations that spec lookup cannot evaluate. A null common effect or requirement means that callers must inspect the variants, not that the effect is absent.

Path	Behavior
symbol, timeframe, type	Omit the positional argument to read; provide it to change the selected chart. Chart-type names/codes use the execution table.
range	Neither bound reads; both bounds request a range change and may load older history. One bound alone is rejected. Bounds must be finite with from < to.
info	No symbol reads the selected chart; an explicit symbol uses credential-free symbol_search_rest without switching the chart.
state	Reads the selected chart's current state and readiness clues.
readiness	Checks Desktop/chart/bar readiness; a successful envelope may contain ready=false.
tab list	Lists targets without activating them. data.tabs[].id supplies --target-id; it is not the numeric index used by tab switching.

Examples containing <target_id> require a selected live ID. Specification lookup never obtains one or changes the chart. Desktop authentication is left unknown because session/data access belongs to the running application; these commands do not use MCP OAuth. A null output contract means no versioned contract is advertised here. Other Desktop commands remain explicitly unannotated, including other data/export paths.

Desktop lifecycle and comparison

Path	Effect and follow-up
launch	Reuses a responding CDP endpoint. Otherwise may start the app and, with --kill-existing, terminate an existing session first. Inspect readiness and warnings.
tab switch	Activates a chart target using data.tabs[].index from tab list.
tab new	Activates the source chart, then opens an app tab. --from uses data.tabs[].index; omission requires exactly one chart tab.
tab close	Closes an app tab using data.app_tabs[].index, not the chart index. Refuses the last app tab.
chart compare	Visits 2–10 symbols on the selected chart, attempts restoration after each read, and stops on an item error. Restoration is not guaranteed.

A responding CDP endpoint is reused even if --kill-existing was passed. Starting an app requires an installation or a valid explicit executable file; process startup does not prove chart readiness. Specs do not probe processes, paths or endpoint availability.

Tab indices can change between listing and execution. Select from the correct list, and inspect the new list after a mutation. App-tab operations also need a usable app-window UI. --target-id cannot substitute for their index arguments. If creation or closure returns an error, inspect the application before retrying.

Chart comparison is an operation with temporary changes, not a read-only query. The output retains per-item status and restoration evidence, final chart context and a summary. Successful JSON can contain partial results. Desktop-free tv compare remains a separate scanner-backed workflow, never a fallback.

Replay practice

Specs cover all seven Replay commands: start, step, stop, status, autoplay, trade and log. Status is read-only; the others change Replay or practice-position state on the selected Desktop chart. Replay trades are not broker orders.

start --date accepts a calendar date; omission selects the first available date. Availability depends on the chart and timeframe. Startup failure can attempt to stop Replay, so an error does not establish unchanged state. Step, autoplay, trade and log require an already-started session. Stop handles an already-stopped session without starting it.

autoplay toggles playback on every call. A positive --speed changes the delay in milliseconds before toggling. Zero or omission keeps the delay and still toggles; zero does not mean stop. Specs use the model's accepted delays and practice-trade actions.

log advances 1–100 steps and emits replay_step_log.v1 JSONL on stdout. Its summary reports actual progress and the end state; the command does not start or stop the session. OHLCV summary attachment is optional, and an explicit count requires its attachment flag. Chart screenshots require both the flag and output directory. They use deterministic replay-step-0001.png names without overwrite. Setup can create the directory before session readiness is known. Attachments follow successful steps; an attachment failure does not repeat the step. Specs describe conditional file effects rather than classifying logging as a read. Specification lookup writes no attachments and always returns its own normal JSON envelope, even when describing this JSONL command.

UI operations

All ten ui commands have semantic details. find observes elements; click, hover, keyboard, type, scroll, panel, fullscreen and mouse can change the UI. eval has unknown effects because it runs arbitrary JavaScript. Spec lookup never connects to the page or enables TV_ALLOW_UNSAFE_UI_EVAL; actual eval requires that variable to equal 1.

Find supports text, aria-label and CSS queries. Click/hover support text, aria-label, data-name and class-contains, but not CSS. Discovery results are observations, not stable identifiers; inspect the first matching target before acting. Hover can change a menu or tooltip. Find returns at most 20 rows and does not prove complete UI coverage.

Keyboard shortcuts and typed text go to the current focus. Type output includes a text prefix, so it is not a credential-entry workflow. Coordinate clicks use the current page geometry. Scroll amounts must be finite but may be negative; scrolling does not establish a requested date range. Panel actions default to toggle, and fullscreen also toggles. Repeating these calls can reverse state.

UI mutation does not imply a known account effect: the focused element or page code determines that. Specs leave account effects unknown except for find. Prefer a dedicated operation when available and inspect the result before retrying a UI input. Names in examples require the user's selected UI target; examples do not authorize account changes.

Chart indicators

Specs cover indicator add/get/set/toggle/remove and the equivalent data indicator read. Resolve chart-local entity IDs from data.studies[].id in tv state on the selected target. Names are not IDs. Get may omit long string inputs and leave visibility/inputs unknown; it is not a complete export.

Add resolves a trimmed, case-sensitive metainfo description with exactly one candidate. There is no dedicated metainfo search command. Supplied inputs must be a nonempty JSON object with scalar values and JavaScript-safe integers; keys must match that metainfo. Insertion is awaited and one new study with the requested name/inputs must be verified. Failure can attempt cleanup, but does not guarantee rollback. Inspect mutation and cleanup evidence before retrying.

Set accepts a nonempty object and updates matching input IDs. Other keys can remain unmatched even on success; no match fails. Its local validator does not apply add's scalar restriction. Returned updated values are requested values, not verified persistence; inspect unmatched inputs and read the study again.

Toggle is a setter despite its name: no flags or --visible shows the study, --hidden hides it, and both flags are rejected. The operation reads visibility back. Remove checks absence of the same entity ID after removal. Specification queries do not perform any of these operations.

Drawings

Specs cover shape/position/list/get/remove/clear on the selected chart. Position drawings are visual objects, not broker orders. List supplies data.shapes[].id for get/remove; IDs from another chart are not interchangeable.

Shape coordinates must be finite. Second and third points each require both price and time. A third point requires a second point, type parallel_channel, time3 == time, and no nonblank text. That path has dedicated point/identity verification; ordinary one/two-point creation observes IDs/counts rather than verifying every property. Generic shape types remain runtime-dependent, not an invented local enumeration. Overrides must be a JSON object, which may be empty.

Position direction is either positional or --direction, never both. Long requires stop_loss < entry_price < take_profit; short reverses those bounds. Prices/time must be finite and optional account-size/risk/lot-size values must be positive. Without entry-time, execution uses the visible-range end or current Unix time. Levels round to the selected symbol's pricescale; inspect the drawing rather than assuming exact geometry from input prices.

Clear defaults to deleting every drawing on the selected chart and checks an empty inventory afterward. --dry-run reports targets/counts without deletion; it does not freeze the set for a later invocation. Empty inventory is a no-op. Remove checks absence of the selected ID. Errors after mutation require reading current state before retrying; no rollback is guaranteed by specification lookup.

Panes and saved layouts

pane list/layout/focus/symbol operate on the current Desktop chart collection; layout list/switch enumerate and load account-saved charts. Pane layout codes come from the execution catalog. Pane indices come from data.panes[].index and are distinct from tab indices and saved-layout IDs.

Pane focus attempts a click but does not verify active-pane identity. Symbol first focuses, then changes the active chart; its returned symbol echoes the request. Read pane list afterward to check the intended pane. Pane layout returns both requested layout and observed_layout without asserting equality. These limitations remain visible in the specification rather than upgrading existing mutation results into stronger evidence.

Saved-layout selection matches an exact ID first, then a case-insensitive exact name, and rejects ambiguous matches. layout switch --dry-run resolves the selection through Desktop without loading it. Normal execution can navigate; switched is not proof that loading finished. The command reports observed unsaved-change dialogs without dismissing them. Refresh targets after navigation and inspect the intended chart before continuing. layout list is inventory, not active-layout readback; inspect data.error even with a successful envelope.

Pine source and Editor operations

All thirteen Pine paths have semantic details. Analyze and alertconditions read UTF-8 source from --file or non-terminal stdin and run locally. Check uses the same input selection but sends source to the credential-free Pine facade; it is neither offline nor official MCP. No source-input command implicitly reads the Editor, and none writes a local file. Static findings and best-effort alert condition indices do not establish successful TradingView compilation.

Desktop get/errors/console may open the Editor. Set and new replace and verify text without creating a new saved-script binding. In particular, new writes a template into the current Editor; saving afterward can affect the existing script. Open resolves a unique saved name and verifies identity/version binding without source-only fallback, saving or compilation.

Compile may add or update a chart study and returns markers and study counts; those observations are not exact study identity or runtime correctness proof. Raw-compile can also invoke a save action and returns no diagnostic verification. Save requires explicit saved/clean UI evidence for an already named script; it does not handle naming a new script or independently retrieve a saved revision. Errors reads current markers without compiling, while console reads visible log entries. Empty markers or logs do not establish a fresh successful execution. Saved-script list can return data.error inside a successful envelope.

Selected-chart data and capture

Ohlcv reads recent loaded chart bars without moving the viewport. Count defaults to 100 and clamps to 1–500, so zero requests one bar. Export chart-bars instead rejects counts outside 1–500 and defaults to 500. It changes the visible range before reading recent bars; the output is JSON on stdout, not a file or a range-filtered historical dataset. Inspect requested and returned ranges and the range-match diagnostics. The previous viewport is not restored on completion or a later read failure. Summaries are derived aggregates; missing numeric fields can be skipped or defaulted by the current summarizer.

Scroll uses loaded bars and an approximate time window around the date. It does not request older history or verify that the final viewport is centered exactly there. Its date/window fields describe the request; use range for readback.

Screenshot writes a local file, creates missing parent directories and overwrites an existing output. Full captures the page, while chart and strategy capture a visible region; the operation does not open Strategy Tester. Clipped capture can fall back to a crop of the full page. Render waiting is optional, with a 500–30000 millisecond bound and 5000 millisecond default. A timeout argument requires the wait flag. Stable observations do not guarantee every pixel or fresh market data. Wait failure precedes capture/write, but a file-write failure is not atomic. Replay screenshot attachments retain their separate no-overwrite behavior.

Credential-free symbol search and bars

Search returns up to 15 candidates, not an exhaustive list. Choose a qualified data.results[].full_name when the exchange matters. Bare-symbol bars lookup selects the first exact symbol match from search rather than rejecting multiple exchanges. Inspect requested_symbol and resolved_symbol. Symbol resolution can perform network I/O before later bars validation; specification lookup stays offline even when an execution would fail validation.

Bars uses the undocumented, unauthenticated WebSocket route with split adjustment requested. It does not imply MCP/Desktop equivalence, verified entitlements or realtime data. Recent mode defaults to 100 bars and accepts 1–500. Date-range mode requires both dates, defaults to a 500-bar cap and permits up to 5000. Range mode supports fewer timeframes than recent mode; exact choices and aliases are in the specification. Filtering uses period-start timestamps and includes the entire UTC to date, without expanding weekly/monthly bars into daily coverage.

Count fulfillment and period coverage are separate. A complete range can contain fewer bars than its cap, while reaching a cap need not cover the requested period. Read range_coverage_status, range_fetch_summary and data_quality.completed; summary.coverage_status and data_quality.partial_result describe count fulfillment. Timestamp-bound coverage is not a trading-calendar gap audit. A failure stage locates the error but does not authorize repeated requests or provider fallback.

Quote source selection and scanner field discovery

Quote semantics depend on both symbol and source. Without a symbol, the default, chart and auto routes read the current Desktop chart. Scanner and quote-data require a symbol. With a symbol and no explicit source, quote uses scanner REST; explicit chart can temporarily switch the chart symbol and attempt restoration. Bare-symbol comparisons do not establish strict identity across exchanges. Inspect observed symbol and restoration/freshness evidence.

Auto falls back to scanner only when connecting to Desktop fails. Once connected, it uses the chart path and returns its failures without scanner fallback. Quote-data instead observes Desktop network events and returns quote_data.v1; it neither switches symbols nor participates in auto routing. Scanner extended hours, chart last-bar/session data and quote-data rtc/lp have different meanings.

Quotes accepts 1–25 nonblank symbols and preserves order, requested_index and duplicates. Mixed results use a successful envelope with per-item errors; all failures produce an error with ordered batch details. Missing session prices stay unknown rather than borrowing another source's value.

Scanner metainfo discovers fields for america. Repeated --field values are trimmed/deduplicated; omission requests all available fields. Inspect missing_fields and optional metadata. This discovery is a provider read, not proof that every requested field or scan capability is available.

Chart analysis and strategy reports

Values reads formatted data-window observations, preserving separate same-name studies and optional identity, visibility and compact inputs. It can omit studies without readable values and include hidden ones. Values are not timestamped numeric series, and absence is not zero. Use same-chart entity IDs and inputs to distinguish instances; the command accepts no per-study selector.

Strategy, trades and equity select the only candidate or, among several, the only report-bearing candidate. Unresolved ties remain ambiguous; hidden and unready candidates remain unavailable. These reads do not open Strategy Tester or change visibility. Inspect strategy_context and data.error even when the envelope succeeds. Report availability means some capability was detected, not that the requested reader has usable data.

Metrics and trades can fall back to already rendered DOM content. Its strategy identity is not independently verified by strategy_context, and row/metric shapes differ from internal report data. Trades defaults/clamps to 1–20 entries, with no newest-first guarantee or pagination. Compare total and returned counts where available; DOM content may be only the rendered subset.

Equity retains report buyHold, equityData, then strategy-bars precedence. series_source records that branch as report_buy_hold, equity_data or strategy_bars. series_kind identifies Buy & Hold as buy_and_hold; other series remain unconfirmed, not guaranteed strategy equity. Rows retain their existing shape; strategy bars preserve zero drawdown and use null for missing values. Performance-only output reports performance_summary with series_kind=unavailable; empty/error output uses unavailable for both labels. Confirm series meaning before calculating returns. equity_summary with data_points=0 remains summary-only.

Pine graphics summaries

Data lines/labels/tables/boxes read Pine primitives on the selected Desktop chart. Their filter is a case-sensitive name substring without trimming; an empty filter selects all readable studies. Rows lack study entity IDs, so duplicate names can remain ambiguous. Missing primitives and suppressed per-study errors can omit rows. These commands neither filter by visibility nor read hand-drawn objects.

Lines round y endpoints to two decimals before horizontal comparison, deduplicate levels and sort descending. Boxes similarly round/deduplicate high/low zones. Verbose output adds primitive detail but does not restore precision or establish coordinate units. Neither summary validates a trading level.

Labels omit entries lacking both text and numeric y. Max defaults to 500 per study, accepts zero, and keeps the last readable entries in primitive iteration order. Counts distinguish extracted, readable and returned labels. This is not a chronological/pagination guarantee or a Desktop collection limit.

Tables group and sort integer table/row/column keys, default missing keys to zero and overwrite duplicate coordinates. Output contains only row strings joined with |, dropping empty cells/rows and original coordinates/IDs. Delimiters in text are not escaped; the result cannot reliably reconstruct a typed rectangle. There is no tables verbose or max option.

Scanner page and aggregate modes

Scanner scan defaults to the first page, with limit 20 and a 100-row clamp; zero is rejected. An explicit offset selects one page and adds offset to the otherwise flattened page payload. Max-results selects sequential aggregation and conflicts with offset/limit. Page-size requires aggregate mode. The spec lists limits, fixed field choices, defaults, filter domains and CLI argument IDs.

Max-results is a permitted population ceiling, not a top-N request. Aggregate requires numeric totals within that ceiling and exact expected page sizes; missing totals, incomplete/overfull pages and request failures return errors. Rows deduplicate by exact symbol, retaining first occurrence. The result includes duplicate and total-drift observations, request fingerprint and start/end times. It is not an atomic snapshot: membership and ordering can change without a total change. The fingerprint identifies query fields, not a frozen dataset.

Both modes use credential-free scanner REST, not Desktop Screener or official MCP. Column/sort fields use a local allowlist; provider metainfo is a separate catalog. Numeric filters must be finite; price/volume/valuation thresholds are nonnegative, signed performance/change thresholds may be negative, RSI is 0–100 and recommendations are -1–1. Provider operators are greater/less; min/max pairs are not checked for ordering. Inspect the actual filters rather than assuming inclusive thresholds or a sensible interval.

Snapshot and comparison packets

Snapshot and compare assemble scanner quote, REST symbol info and scanner fundamentals without Desktop or MCP. They return snapshot.v1 and compare.v1. Sections are separate observations, not a synchronized dataset. Snapshot accepts one symbol and fundamentals group/field selection; compare accepts 2–25 symbols, preserves order/duplicates and uses default fundamentals fields. Group expansion precedes explicit fields and deduplicates them; specifying either replaces the default selection only for the fundamentals section.

Any successful section makes a symbol packet successful. Compare resolved_count therefore does not count fully populated packets. Complete coverage checks section success and tracked fundamentals missing fields, not every quote/info field, identity agreement, freshness or entitlements. All-section/all-item failure retains the packet in outer error details. Use sections, errors and missing_evidence alongside summary. The top-level symbol uses quote, then fundamentals, then info rather than requiring cross-section agreement.

Follow-up hints do not execute or authorize actions. Their non_mutating flag means no chart mutation: chart_quote is false because it can switch/restore a symbol, while screenshot remains true. effects.chart_mutation and effects.local_file_write describe those possible effects separately; screenshot has the file flag true. Read-only hints have both false. Packet-level non_mutating remains true because producing hints executes none of them. Inspect the hinted command's own specification before acting.

Official MCP screener

MCP screener requires authentication and remains Desktop-free. Its specification uses mcp_screener.v1 and the common read timeout metadata. Filters are a JSON object with up to 50 fields and 16384 input bytes. Numeric bounds are two finite numbers or nulls with min <= max; index, sector, industry and analyst_rating also accept strings. Columns use shared defaults and uniqueness limits. Types and symbolset are optional exact-unique string lists; their provider meaning is not validated by local shape checks. Presets are explicit accepted names, not trading judgments or a replacement for technical indicator observations.

The single read has no paging/offset. Empty success is valid, while inconsistent counts, duplicate symbols and malformed identities fail normalization. Count coverage limited/all_reported/unconfirmed does not establish exhaustive market coverage; item missing fields remain distinct from explicit nulls. Data time, delay and session remain unconfirmed. Regional screener market syntax is separate from column-discovery categories. Credential refresh may update local state; specification lookup itself reads no credentials or provider data.

Official financial data

Financials, financial-history, forecasts and earnings share authenticated read prerequisites and timeout metadata. Financial snapshots accept fy/fq/ttm/fh/current and up to 50 unique metric names; omission leaves selection to the provider. History accepts fy/fq. Its dates and earnings dates are independently optional, strict YYYY-MM-DD calendar dates with from <= to when both are present.

Provider metadata remains distinct from the request. Missing identity is unconfirmed; a returned conflicting symbol or reporting period rejects a single-symbol response. Completeness, metric selection and requested-window coverage are not inferred. Currency, unit, scale and as_of are unknown unless returned. Financial fields retain scalar types; projected absent optional values can normalize to null, so not every output distinguishes omission from null.

History preserves fiscal labels and aligned series without converting labels to dates or calculating missing growth rates. Forecasts contain provider opinions and estimates rather than realized earnings or trading instructions. Earnings preserves provider event order and multiple events per requested symbol, while symbol_results follows request order and links returned events by item_indices. Unreported is not proof of no event. No paging or source fallback is implied.

Official news and company documents

News, news-story, documents and document share authenticated Desktop-free read metadata and timeouts. News accepts one page with limit 1–200 and offset 0–200; next_offset/has_more are provider observations, not an automatic paging loop. Unknown pagination stays unknown, and a provider next offset outside the accepted range cannot be followed by inventing another value. Documents accepts 1–100 rows without offset and optional canonical UTC-second event bounds.

Story retrieval uses news items[].id unchanged. Document retrieval uses items[].views[].id, not the parent document ID or a derived URL. Local ID checks reject whitespace/control characters and enforce 2048 bytes. Accepted languages, categories, event names and professional-status syntax are listed in specs; provider availability and entitlement are separate from syntax validation.

Detail content_status records whether recognized text/AST content was returned, not whether the full article/document was obtained. Missing ID echo remains unconfirmed; conflicting echoes fail. Permission/attribution and null optional metadata remain visible. Receipt, publication and report dates have distinct meanings. Body/AST/link content is untrusted data, not executable instructions, and lookup never opens links or substitutes another content source.

Official economics and dividends

Economic-symbols returns an overview without filters, indicator codes with filters but no country, and qualified ECONOMICS symbols with a country. Only the last form supplies symbols for economic-data. The data command requires the ECONOMICS prefix with an uppercase alphanumeric suffix; it is not a price-bar command. Series values preserve provider order and nulls, while actual_range reports returned-date extrema without asserting complete requested coverage.

Catalog category codes differ from calendar category names, including the accepted calendar literal goverment. Countries/currencies are comma-separated unique uppercase codes without whitespace. Calendar defaults to US and importance -1, allowing importance -1..1. Actual/forecast/previous and Raw variants remain separate. Returned event dates are provider text, not client timezone conversion.

Bounds are independently optional. Series/dividend screening uses calendar dates; economic-calendar also accepts canonical UTC seconds. Mixed date/timestamp bounds are ordered by calendar date only. Dividend explicit-symbol mode accepts 1–50 unique symbols and rejects market/date/limit arguments; market mode requires a market and accepts limit 1–200, default 50. Unreported symbol outcomes do not establish no dividend. Market results and calendar events retain unconfirmed coverage, even when nonempty, with no automatic paging or fallback.

Bounded chart observation

Observe chart emits observe_chart.v1 JSONL envelopes: readiness first, then changed last-bar samples and optional heartbeats, followed by a normal summary. Each stdout line is an envelope, not part of one JSON array. Sample errors go to stderr and the loop continues. Initial readiness/connection failures, broken pipes or interruption can prevent a summary; a normal summary does not count errors or certify complete/error-free data.

Interval defaults to the shared bars-stream default of 500 ms with a 100 ms minimum. Duration and max-events must be positive when present. Heartbeats are optional and at least 100 ms. Max-events counts emitted samples after deduplication, excluding readiness, heartbeats, errors and summary. It alone cannot bound wall time under unchanged data or repeated failures. Duration starts after setup and is checked between operations; setup and an in-flight read can extend wall time.

Polling does not capture every tick or guarantee closed bars. _ts is client milliseconds and bar_time is the chart timestamp. Volume follows the existing reader's zero default. External chart changes are not prevented; inspect symbol and resolution per sample. No symbol switch, tab activation, screenshot or source fallback is performed by observation itself.

Primary chart streams

Stream values, quote and bars emit stream.v1 JSONL without an initial readiness event. They share observe chart's deduplicated sample counting, continued sample errors on stderr and termination limits. Quote defaults to 300 ms; bars and values default to 500 ms. The minimum interval is 100 ms.

Values reads numeric properties from studies' internal last-bar data rather than repeating the formatted data-window read used by values. Explicitly hidden studies are skipped when visibility is readable; unavailable studies and per-study failures can be omitted. Unknown visibility remains unknown. Identity and compact input changes affect deduplication. There is no study filter, explicit timeframe field or guaranteed per-study timestamp in these samples.

Quote and bars both read the current main-series last-bar OHLCV. Quote uses time and omits resolution/bar_index; bars uses bar_time and includes those fields. Neither is a scanner/MCP quote feed or a historical bars export, and polling can miss intervening changes. Missing/falsy volume follows the existing zero default. Verify chart context before collecting; external chart changes remain possible.

Pine graphics and layout streams

Use stream lines, stream labels or stream tables for repeated Pine graphics reads. Their optional --filter is a trimmed, case-insensitive substring of the chart study name, unlike the single-read data commands. Rows have study names but no entity IDs, so same-name instances remain ambiguous. Hidden studies are not excluded. Unreadable primitives and individual study failures can omit rows; study_count is the returned row count. Samples lack resolution and primitive timestamps. Verify chart and script coordinate context before interpretation.

• Lines returns unique raw endpoint levels sorted descending. Sloped lines also contribute an endpoint; these are not verified horizontal levels. Truthy endpoint fallback can replace zero, and coordinates/IDs/styles are omitted.
• Labels keeps nonempty text and the first 50 entries per study in internal iteration order, without truncation counts or configurable limits. A zero y fallback can become null. Label IDs and x coordinates are absent.
• Tables returns nested text rows rather than the pipe-joined data tables summary. Styling, primitive IDs and proof of complete extraction are absent.

stream all reads last-bar OHLCV from chart panes in the current layout; it does not combine the other stream kinds. Inspect each pane's error even when the sample succeeds. pane_count includes failed panes and indexes describe current widget order, not stable identities. Successful rows have symbol, resolution and time; missing volume can default to zero. Panes are read sequentially, without an atomic cross-symbol snapshot guarantee or a saved-layout/tab switch.

Defaults are 1000 ms for lines/labels, 2000 ms for tables and 500 ms for all. Use tv spec stream <kind> when available and help otherwise. The same JSONL error channels, deduplication and duration/count limits described above apply.

Official account discovery

Watchlist list returns items in provider order with decimal-string IDs. Pass the selected ID unchanged to get, which returns watchlist and checks its ID against the request. IDs allow zero and reject leading zeros/whitespace. Preserve symbol order and section labels; a section label is not a tradable symbol. symbols: null is unknown, not an empty list.

Alert list accepts an optional qualified symbol and explicit --active true or --active false; omission leaves active state unfiltered. Known response fields that contradict filters fail, but null fields remain unknown. List rows retain provider order and positive numeric alert IDs. Get accepts 1–100 distinct IDs up to 9223372036854775807. It returns requested order with requested_id, status and nested alert. An unreported ID has a null alert and does not prove deletion. returned_count counts actual alerts, not placeholder rows; check ids_status and unreported_count. Unexpected or duplicate IDs fail.

Successful transport does not establish complete account coverage. These reads have no pagination controls or automatic traversal. Receipt time is client time; account time fields remain provider strings. Conditions are a limited projection with unknown completeness, insufficient to recreate complex Pine alerts. Messages and webhook URLs are excluded; notification flags do not establish delivery. Keep account IDs and returned account data private.

Authorization command specifications

Use tv spec mcp status, tv spec mcp login or tv spec mcp logout when available to inspect effects without performing the operation. These success payloads use the ordinary CLI envelope without a separate versioned data contract. All three acquire the local per-user lock and can create local state/lock files; local-only operations can still fail on storage access or lock contention.

Status does not refresh tokens or contact the provider. Unknown expiration yields null expiration/expiry fields. A readable record or locally_expired: false does not establish provider acceptance. next_action is null when a record exists, even if later login may be needed. Storage errors are not equivalent to missing credentials.

Login discovers OAuth metadata even when it reuses credentials and may refresh and save them. Fresh authorization registers a client, requests mcp:read via PKCE and waits for browser consent through a loopback callback. Human progress messages appear only on terminal stderr; agents capturing output must explain and await browser/OS actions themselves. Login success leaves provider acceptance unconfirmed because it does not call a data/account tool.

Logout deletes only the dedicated local record. It neither signs out the browser nor revokes remote grants, changes account objects or resets provider limits. It does not authorize OS interaction: a required deletion prompt produces an error and needs a separately arranged credential-manager action. Default budgets are 300 seconds for login and 30 for status/logout. None accepts --timeout.

Visible read limits

When supported, inspect the chosen tv spec screener command path before use. Status reads current state without opening the panel. Get, screens active, filters list and columns list can temporarily open a closed panel, then attempt to close it with Escape. opened_for_read records the opening; restored_open_state is the initial open boolean, not a success flag. False is expected after a successful closed-to-open-to-closed read. Returned open is the captured state, not necessarily the final state. After errors, check actual UI state because opening or cleanup can fail.

Get defaults to 20 rows and clamps positive limits to 100; zero is rejected. It does not scroll or paginate. visible_row_count counts DOM table rows, not total matches or strictly viewport-visible rows. Cells contain localized display text. field_values uses displayed column labels, so duplicate labels overwrite keys and missing headers can misalign values. Row text is truncated to 500 characters.

Screens active returns title text, not a saved-screen ID. Filter pills are not a full filter definition. Columns list returns displayed names and positional indexes, not storage column IDs. Inspect config/actions before editing. For data-only screening use official MCP when it meets the requested criteria; it does not reproduce saved Desktop screen state. Never silently substitute sources.

Existing Desktop watchlist read

Use tv spec watchlist get when available to inspect this distinct Desktop operation. It reads rendered right-panel content without selecting a list by ID. Closed/missing panels can return successful empty rows. Extracted symbols are deduplicated; rendered content does not establish full account-list coverage. The source field reports panel_closed, no_container, data_attributes, text_scan or empty. Data-attribute reads infer last/change/change_percent from numeric cell strings; text scans can return unqualified ticker-like names with null prices. Neither confirms symbol identity or freshness.

Prefer explicit tv mcp watchlist list followed by get <ID> for account-list contents. MCP preserves sections and ordering but does not reproduce visible quote cells or establish which list is selected in Desktop. Do not switch sources after a failure without deciding that the alternative meets the request.

Screener edit discovery

Screen lists read the title menu by default or open the catalog with --catalog. They do not enumerate all account storage. Names and indexes are UI observations; IDs and owner/shared flags can be absent. Scope and exact names matter when selecting a target. Screen actions report recognized menu entries. save_enabled means an enabled save candidate was seen, not that saving succeeded.

Filter actions probes one numeric-filter candidate's manual-range popover. Its range_options does not describe every filter. add_supported is currently false because this probe does not verify the add catalog; a separate filter-add command exists. Column actions reads settings categories, while its header-menu actions are currently empty. Thus remove_supported and reset_supported are false even though a separate storage-based remove command exists. Reset remains unimplemented. Treat these flags as limits of the probe, not a CLI capability map.

These menu probes change visible UI even when the Screener is already open. Successful paths attempt to close their popups and any panel they opened, but do not reconstruct prior popup/focus state. Early failures can bypass cleanup. restored_open_state is the initial panel state, not cleanup success.

Columns config instead requires an already open panel and reads screen storage using the Desktop session. It does not open menus or use MCP OAuth. Missing init data, failed fetches and exact title mismatches fail. Matching titles alone cannot distinguish same-title screens. Returned storage fields can fall back to loaded init data, so they need not match unsaved UI edits. Column id and params come from storage, while name is paired by visible position and identified with name_source: visible_column_index; this is not an ID-based name match.

Keep screen IDs/names and configurations private. Official MCP screening can answer suitable data queries but does not supply these saved-screen menus or storage definitions. Reread target state before a separately requested edit.

Saved-screen changes

Dry-run still connects. Switch/save inspect menus; create/rename/save-as can open and focus name dialogs without submitting. Delete preview fetches account storage. Cleanup attempts do not reconstruct prior popups or roll back selection/edits. restored_open_state is the initial panel state, not a cleanup-success flag.

Action	Execution boundary and evidence
switch	Resolves one exact name in the title menu or --catalog scope. Missing/duplicate matches fail. An already-active title returns switched: false; otherwise the new title is observed and left active. No test-name restriction.
save	Targets the active screen, with no name argument or test-name restriction. Requires an enabled save action. save_requested: true with confirmation: not_observable confirms the request, not durable storage.
create / save-as	Execution requires a destination name containing case-sensitive CLI-Test or テスト. Opens create/copy dialog, submits and waits for the new active title; this is not a uniqueness, content-equivalence or storage audit.
rename	--name must match the active title even in preview; --to must differ after trimming. Execution requires the test substring in both names. Success observes the new title, not independent persistence.
delete	Resolves an exact saved name through storage. Execution requires a test name and --confirm-delete, and refuses an active target. Preview can report an active target without rejecting it. After deletion by ID, checks name absence in a fresh list.

Names are trimmed and must be nonempty. Test-name limits are enforced by the CLI, not merely a recommendation for verification. User permission does not remove these implementation restrictions. A failed post-check can follow a completed write; inspect current state before deciding what to do next. Do not blindly repeat create/copy/rename/delete or claim that an error rolled the change back. Keep real names, IDs and account storage replies private.

Saved column changes

Inspect tv spec screener columns <action> when supported. Add/remove/reorder require an already open Screener and readable active saved configuration. They use the Desktop session to fetch storage; they do not open the panel or force a UI refresh. Execution is restricted to active screen names containing the case-sensitive substring CLI-Test or テスト. Dry-run still reads storage, but only calculates the proposed after_columns without saving.

• Add uses a trimmed nonempty storage --id and optional JSON-object --params-json (default {}). Omitted --after-index appends; a supplied zero-based index must refer to an existing saved column. Duplicate IDs/params are not rejected locally, and preview does not verify provider support.
• Remove requires exactly one of --index or a nonblank --name. The name is a case-insensitive substring and must match one visible column. The visible index then selects the saved column at that position; verify ID/params because this is not an ID-based match. No local guard prevents removing the last column.
• Reorder requires distinct in-range saved --from-index and --to-index. The destination is the final position after removal, not an insert-after position.

Execution writes the fetched screen document with the new custom column sequence and active_column_set: custom. It reads storage back and compares ordered ID/params pairs and count. This does not verify refreshed UI, displayed data or every screen field. Returned names derive from earlier positional mapping, not a fresh identity check; init-data fallback can also differ from unsaved UI state. Intervening edits are not reconciled by the adapter.

A write may complete before readback fails. Inspect current storage before retrying, especially add, which can insert duplicates. These are account-setting changes, not temporary display toggles. Official MCP does not edit these saved column sets. Keep account-local configuration and IDs private.

Filter changes

Inspect tv spec screener filters <action> when available. Filter operations use different UI and storage paths; do not infer one persistence or permission rule from the command family. UI add/modify has no test-name guard. Execution of storage remove/clear/range-modify requires CLI-Test or テスト in the screen title. These are code restrictions, separate from permission to edit.

Add searches the catalog and matches an existing range option. Supply a nonblank name and at least one finite bound; with both bounds, max must exceed min. Dry-run finds only the candidate, not the requested range option. Success checks a new matching visible pill, not saved storage. Recognized greater/less labels do not establish a uniform inclusive-bound interpretation.

Modify/remove require either a zero-based index or nonblank text, not both. Text uses a case-insensitive substring and must match exactly one visible pill. Modify accepts either a nonblank option or numeric bounds. Numeric presets are: min-only 3, 5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90; or min 0 with max 3, 5, 10, 20, 30. Max-only is rejected for modify although add accepts it. These are preset selectors, not arbitrary numeric input.

Option modification prefers a normalized exact match, then a unique substring match in either direction. It can clear other selected options before selecting the target. Preview opens the popover; it is not an additive multi-select API. UI readback checks pill text, and an already-matching pill can return no change.

If both the panel and its open button are absent, numeric modify with an index can first try current-screen storage. It supports only simple Condition above/between filters and still applies the public preset bounds; stored bounded ranges require exact zero. Unsupported preflight can proceed to the UI path, but failed post-write verification does not. The storage path requests reload without confirming visible readiness.

Remove and clear previews inspect visible targets only. Execution validates the test-name guard and equal visible/storage counts, then maps by position. Count agreement does not prove filter identity. Clear also requires --confirm-clear and writes an empty saved filter list. Storage writes replace filters in the fetched screen document and compare ordered definitions on readback, without reconciling intervening edits.

For remove/clear, a full-page target can reload and poll filter count; visible_refresh.confirmed checks only that count. False or skipped refresh can accompany a successful storage change. Dialog targets skip reload. Neither this flag nor pill text proves row coverage, freshness or every filter condition.

Dry-run can change panel/popover/focus state and can read storage. restored_open_state is the initial panel state, not cleanup success. Failures can leave UI or saved settings changed; inspect current state before retrying. Official MCP can answer a suitable data-only query but does not edit these Desktop filters. Keep account settings and IDs private.

Legacy Desktop watchlist changes

Prefer official tv mcp watchlist list/get followed by an explicit list-ID mutation when it meets the request. Legacy watchlist add/add-bulk/remove needs Desktop and targets the active list; it has no list-ID or dry-run option. Use tv spec watchlist <action> when available to inspect its behavior offline. Do not silently replace a requested source or target.

The legacy path first tries the Desktop-session internal API. DOM fallback is limited to recognized pre-dispatch list failures; once a POST is attempted, transport, HTTP and readback failures stop without a second DOM mutation. Readback requires the original list ID and readable symbols, even if another list becomes active. Failure does not imply rollback. Older binaries can replay uncertain writes through DOM or check another list; inspect the installed spec. DOM paths can open the panel and alter focus/input without restoring it. Rendered-row counts and presence/absence are not complete account-list evidence.

Symbols are trimmed and must be nonempty, with no case normalization or strict exchange qualification check. Legacy add skips an exact existing member; official MCP add instead moves an existing member to the end. Legacy remove reports an absent member as an error. DOM remove uses a row control and does not confirm a deletion dialog. Inspect the actual source and outcome before continuing.

Bulk add allows at most 50 unique trimmed symbols, deduplicated case-sensitively. The delay is 0–10000 ms, default 750, between unique attempts. All unique symbols are attempted even after failures; --allow-partial changes only the final result, not continuation. Without it, failures produce an error with the batch payload in details; with it, the payload succeeds despite failed rows. Neither mode rolls back earlier changes.

Read each result and its added/already_present/failed/skipped_duplicate status. Requested count includes duplicates; processed count excludes them. Each item resolves the active list again, so selection changes can split a batch across lists. Do not retry a whole batch or repeat uncertain writes without checking current state. Keep account-local details and raw errors out of shared artifacts.

Legacy Desktop price alerts

Prefer official MCP for supported explicit-symbol price alerts and explicit-ID management. Legacy alert list/create/delete uses the selected Desktop session and private account endpoints. It is not interchangeable with the MCP contract; use tv spec alert <action> when available before choosing it. Pine indicator alerts are a separate workflow, not a simple price-alert substitute.

List returns an error for failed reads or malformed row collections; a valid empty collection still succeeds. Creation/deletion checks use the same strict reader, so unavailable readback cannot confirm success. Older binaries can return outer success with data.error; never treat that as an empty account. Missing active state defaults to true. Provider timestamps are not normalized and projected conditions cannot reconstruct complex Pine alerts. Messages remain in legacy output, so keep account details private.

Create uses the active chart symbol/timeframe. Conditions crossing, greater_than and less_than map to cross, cross_up and cross_down. The internal API uses on-first-fire, auto-deactivation and about 30-day expiry; popup and mobile push are enabled, email/SMS are disabled and webhook is null. Currency can fall back to USD and resolution to 1. These are different defaults from official MCP. There is no dry-run.

Creation uses the internal API and checks a new matching ID, symbol marker, message, condition type and approximate price. API preflight failure returns an error without opening a dialog. There is no automatic DOM or MCP fallback; failed readback can still follow account creation, so inspect before retrying. Older binaries can report source: dom_fallback and created: true after a button click without verifying conditions or persistence; that is not proof of a correctly saved alert.

Delete requires exactly one of --id and --all. Dry-run is supported only with all and performs a fresh account read. Execution of all targets every alert listed at that time, not the chart symbol or a prior preview's fixed set. No separate confirmation flag is implemented. A missing single ID fails; an empty all-target set is a no-op. Numeric-looking IDs are converted to JavaScript Number without a safe-integer bound, unlike MCP's validated integer contract.

Deletion readback checks targeted IDs are absent, not that the account has no newly created alerts. Partial deletion or failed verification does not roll back the write. Inspect current state before repeating a mutation.

Pine indicator alerts

tv alert create-indicator uses Desktop and a saved Pine script; official MCP simple-price alerts do not replace its alertcondition logic. Inspect tv spec alert create-indicator when available. Supply UTF-8 source via --file or nonterminal stdin, --script matching exactly one saved name/title, and exactly one of --condition-title or --alert-cond-id. Use local tv pine alertconditions --file <source.pine> for best-effort candidates.

The command does not save or compile the supplied source or compare it with the saved script version. Plot IDs depend on preceding outputs. Verify that the source corresponds to the intended saved version before creating an alert. The source text is not uploaded; execution sends derived feature/condition metadata, saved script identity/version and study inputs. It does not add a study, alter its inputs or switch chart symbol/timeframe.

Dry-run is live: it connects and reads the saved-script catalog. would_create/mutation_supported only describe preview assembly. Missing script IDs can pass preview but fail execution. Input extraction, chart defaults and provider creation/readback are not exercised by preview.

Execution takes inputs from the first chart study matching a saved/requested name/title. It does not resolve duplicate names by entity ID or verify source version. Returned input order becomes in_0, in_1, etc.; zero returned values do not prove completeness. Textual input detection can be affected by comments or formatting. When inputs are detected and no matching study is available, it fails; otherwise base metadata can suffice without a study.

Optional symbol/resolution overrides do not change the source of study inputs. Missing resolution, currency and saved version can default to 1, USD and 1.0. A trimmed nonblank message overrides the source candidate message, then (none) is used. The request uses dividends adjustment, on-bar-close, approximately 30-day expiry, auto-deactivation off and all notification channels off.

Readback matches an alert not previously seen by ID, its alert_cond type, condition ID and message; symbol is checked only when reported. It does not verify every input, saved version, resolution or notification delivery. Failed readback does not prove no alert was created. No DOM/MCP fallback is performed; inspect account state before retrying and keep script/account details private.

Pine shape and character observations

Use tv data shapes --count <N> [--filter <TEXT>] [--verbose] for Pine plots represented internally as shapes, not hand-drawn objects or line/label primitives. Use tv spec data shapes when available, and help otherwise. Filter is a case-sensitive substring of the first available description, short name or metainfo ID; whitespace is not trimmed. Hidden studies are not excluded.

Count is a per-study bar-index window, default 100 and clamped to 500, not the number of signals. Zero can retain plot metadata with no signals. Results run from newest index backward, with plots in declaration order within each bar. bars_scanned counts the span even when data rows are missing; scan_count is the effective cap. Neither is complete historical coverage.

Numeric zero, false, null and nonfinite numbers are omitted. Nonempty strings and other values can be reported as active; value is not necessarily a price or boolean. Zero-valued absolute-position plots can therefore disappear. Style fields come from metainfo/defaults, not verified rendered overrides, and do not reconstruct all glyphs, offsets or pixel positions.

OHLC uses the main-series row at the same index, without independent timestamp alignment or plot-offset correction, and is rounded to two decimals even in verbose mode. Missing values remain null. Verbose adds plot IDs/indexes/size, not study entity IDs or chart symbol/timeframe. Confirm chart context separately. Per-study errors can omit rows and malformed raw collections can become empty success. Empty results do not prove absent markers, closed bars or valid trading signals; they are bounded observations of currently loaded data.

Status and UI snapshots

Use tv spec status or tv spec ui-state when available to inspect these commands offline. Actual status fetches CDP targets and queries basic chart metadata for a selected target. Without an explicit target, missing or ambiguous chart candidates can return success with connected/cdp_connected false and data.error, even though target enumeration worked. Check target selection and candidates before treating this as an offline endpoint. Connection failures are errors; chart evaluation failures can leave unknown fields after connection.

Neither connected nor api_available proves recent bars can be read. desktop_readiness in status summarizes targets; use tv readiness for the chart/bar check and retain the intended target's returned target_cli_args. These commands do not launch Desktop, switch targets or authorize later edits.

ui-state observes DOM layout and chart/Replay state. Open flags use dimension thresholds or element presence, not proof of usable controls. Button labels are filtered/truncated, and deduplication strips non-ASCII characters; localized or repeated controls can be omitted. Key-button matches are mostly English and can be overwritten by later matches. Coordinates are rounded viewport top-left positions, not verified click centers or stable selectors.

Chart/Replay errors can be embedded in an otherwise successful UI snapshot. Inspect those sections; no bar freshness, complete button inventory or future action readiness is implied. Recheck after UI changes rather than reusing old coordinates, and keep target URLs/titles and UI content private.

Scanner comparison polling

Use tv spec watch compare for offline controls when available. Its readiness is input validation, not a provider probe. Samples contain scanner quotes, not all sections of tv compare. Inspect per-item errors and resolved/error counts. Poll errors go to stderr and the loop continues; successful completion alone is not collection success.

Only changed samples count toward max-events; timestamps and poll counters are excluded from deduplication. The interval starts after the poll completes. Duration is checked between polls, so in-flight requests can overrun it and postpone heartbeats. _ts is client emission time, not market time. Summary last-result counts describe the latest successful poll; inspect poll_error_count as well. A closed output pipe can omit the summary.

Scanner financial and event coverage

Use tv spec fundamentals and tv spec events compare for offline details when available. Fundamentals reads the america scanner market and preserves raw field values. missing_fields lists absent array positions, not explicit nulls; an empty list is not proof of complete financial data. Inspect field_values. The local identity check compares bare symbols, so verify observed_symbol and its exchange against the request. No currency, period or freshness is inferred.

Events compare preserves request order and duplicates. Even when every item fails, its outer response can succeed: inspect item status, failure details and summary.error_count. Successful items contain events.v1, shaped from scanner fields rather than a full calendar. no_events_returned does not prove absence of events. Preserve raw readback and source availability; do not infer timezone, market session or confirmed/estimated status.

Opening and closing the Screener

Inspect tv spec screener open or tv spec screener close offline when available. Default open operates the selected target's dialog and requires its Screener button, even if a panel is already detected. It either reports the existing open state or clicks and waits for panel detection. This does not prove rows are loaded or authorize saved-screen edits.

open --full-page instead activates the first matching Screener target; it does not use --target-id to select that target or reject multiple matches. If none exists, it tries CDP tab creation, then a TradingView new-tab tile fallback on creation error. Post-check can accept another matching target. Inspect tab list first and use the returned target_cli_args for subsequent operations. The created/reused flags describe the path taken, not unique tab ownership or data readiness. Previous focus is not restored; failures can leave tabs or UI changed. Inspect actual state before retrying rather than assuming nothing happened.

close sends Escape to the selected target only when a panel is detected. It waits for panel disappearance and fails if still open; Escape may dismiss a popup instead. An already closed panel returns action=already_closed and closed=false, which is a successful no-op. This command does not close a tab and has no full-page option. A full-page panel may remain detected after Escape; do not automatically substitute a tab-close operation.