#

AskNews CLI

Use AskNews directly from your terminal, scripts, CI jobs, and coding agents. The asknews executable provides polished commands for common research workflows and generated coverage for every customer-facing operation in the AskNews API.

#

On this page

• Installation
• Quick start
• Authentication and configuration
• Commands and output
• Using the CLI with agents
• Complete command reference
• Agentic usage
• API reference

#

Requirements

• Node.js 22.15 or newer
• An AskNews account with API access
• OAuth login or an AskNews API key

#

Installation

The curl installer runs npm install -g under ~/.local by default — no token or registry configuration required. Run it with --help for version, prefix, checksum, PATH, and agent-skill options. After installing, verify with asknews --help.

#

Quick start

Interactive OAuth is recommended:

For a terminal without a browser:

API keys are supported for CI, automation, and agents:

Run a human-readable query:

For scripts and agents:

#

Authentication and configuration

The CLI supports OAuth device login and AskNews API keys. It never requires a client secret.

#

OAuth login

OAuth tokens refresh automatically when a refresh token is available. Stored credentials live in the platform user-config directory with restricted permissions.

#

API keys

For noninteractive use:

For a persistent local login:

The prompt does not echo the key. In CI, use the environment instead of local storage.

#

Authentication precedence

1. --api-key
2. ASKNEWS_API_KEY
3. Stored OAuth session
4. Stored API key

Setting	Flag	Environment variable	Default
API URL	--api-url	ASKNEWS_API_URL	https://api.asknews.app/v1
Auth issuer	--auth-url	ASKNEWS_AUTH_URL	https://auth.asknews.app
OAuth client	--oauth-client-id	ASKNEWS_OAUTH_CLIENT_ID	asknews-cli
Output	--output	ASKNEWS_OUTPUT	human on a TTY, JSON otherwise
Timeout	--timeout	ASKNEWS_TIMEOUT_MS	60 seconds

Never commit API keys or OAuth tokens.

#

Commands and output

The CLI has curated workflows, generated API commands, and a generic request escape hatch. Run asknews --help at any level for the installed version's exact reference.

The complete command reference documents every curated command and generated API group with usage signatures, arguments, options, defaults, enums, safety metadata, and examples.

#

Curated workflows

#

Complete generated API coverage

Every customer-facing OpenAPI operation appears under asknews api, grouped by API tag:

Every schema parameter is exposed as a kebab-case option:

OpenAPI names are converted predictably: start_timestamp becomes --start-timestamp. Repeatable --param name=value remains available as an escape hatch.

Pass bodies as inline JSON or from a file:

#

Generic requests

Prefer curated or generated commands for normal use.

#

Output formats

Format	Option	Best for
Human	--output human	Curated interactive tables
Table	--output table	Force tabular list output
JSON	--output json or --json	Scripts, CI, and agents
JSON Lines	--output jsonl	Record pipelines
YAML	--output yaml	Readable structured inspection

Result data goes to stdout. Diagnostics and errors go to stderr.

Human and table output wraps complete summaries without truncating them. A horizontal divider separates each result so long, multi-line summaries remain visually distinct.

#

Complete option help

Curated and generated commands derive their options from the current public OpenAPI schema. Help includes types, required fields, defaults, enum values, formats, numeric ranges, safety, and the underlying operation:

#

DeepNews models and streaming

List models available to the authenticated account:

Stream research incrementally:

For event-level automation, combine streaming with --output jsonl.

#

Using the CLI with agents

The package includes an asknews-cli skill that teaches coding agents how to select the right retrieval or research workflow, preserve source provenance, control context and cost, recover from common errors, and execute authorized mutations safely. Its core instructions stay concise; an optional task-recipes reference is loaded only for advanced work.

#

Install the skill

The packaged CLI installs its skill into detected global agent directories by default. To install or refresh it manually:

For a repository-local skill:

Use ASKNEWS_NO_AGENT_SKILLS=1 to opt out during package installation.

See Agentic usage for automatic and manual skill installation, capability mapping, context-window guidance, and exact command references.

#

Agent-safe usage

• Use --output json for complete results and --output jsonl for streaming events.
• Use --output table only for human inspection.
• Check asknews auth status --output json first.
• Keep result limits narrow unless broader retrieval is requested.
• Treat archive, graph, forecast, DeepNews, and web search as billable.
• Do not mutate or trigger alerts/newsletters without clear authorization.
• Never print or repeat API keys or OAuth tokens.
• Prefer article retrieval for evidence, stories for evolving events, and DeepNews for requested synthesis rather than using the most expensive workflow by default.
• Preserve source names, links, publication dates, IDs, and returned citations needed to audit the final answer.