Hosted API + CLI Manual

SciAtlas API & CLI Documentation

Use this page when you want to run SciAtlas from the terminal: install the CLI, configure your token, choose a command, understand every parameter, and copy a ready-to-run example.

Start with CLI API Setup Browse Commands Parameter Guide Agent Skills

Overview

SciAtlas is designed to be used from the command line first. The CLI turns your topic, idea, author, keyword anchors, paper-title anchors, and retrieval preferences into a structured request, calls the hosted SciAtlas knowledge-graph backend, and saves reproducible artifacts under a run directory.

Most users do not need to write JSON by hand. Start with expert parameters for stable results, or use natural-language input for fast exploration.

Choose your starting route

All three routes use the same hosted SciAtlas service. Choose based on how you prefer to work, not on which route sounds more advanced.

Name check: a CLI command is a command you run; a CLI JSON preset is a reusable command template; an Agent Skill is a SKILL.md playbook an agent follows. They are related, but they are not interchangeable.
Structured but friendly

Use flags such as --query, --keyword, --time-range, and --top-k instead of hand-writing API payloads.

Report-ready outputs

Every workflow can save request, response, metadata, and Markdown reports for review or reproduction.

Optional LLM help

If you configure your own LLM provider, SciAtlas can improve keyword extraction. If not, it keeps running with deterministic extraction.

API Configuration

The CLI is the recommended entry point, but it still calls the hosted SciAtlas API. Configure the base URL and your personal token once, then reuse them across all CLI commands and client code.

Direct Links

Base URL and Runtime Variables

Authentication Headers

Most hosted endpoints require a valid SciAtlas token. The CLI sends both headers for compatibility.

Authorization: Bearer YOUR_SCIATLAS_TOKEN
X-API-Key: YOUR_SCIATLAS_TOKEN

Browser Registration

Open the registration page, complete email verification, and copy the returned sciatlas_xxx token. The token is shown only once, so store it securely.

http://sciatlas.openkg.cn/register

Token Status and Usage

curl -H "Authorization: Bearer $SCIATLAS_API_KEY" \
  http://sciatlas.openkg.cn/v1/auth/token/status

curl -H "Authorization: Bearer $SCIATLAS_API_KEY" \
  "http://sciatlas.openkg.cn/v1/auth/usage?days=7"

Useful API Routes

Errors and Limits

Errors use regular HTTP status codes plus a short error type in the response body. Each personal token has a daily quota; heavier retrieval routes may consume more units than status checks.

How the CLI Works

A SciAtlas command usually has four parts: global connection options, one task command, input or anchor parameters, and output controls. The CLI then builds a plan, calls the proper backend route, and writes files for later review.

Mental model: use expert parameters when the topic matters, use natural language when you are still exploring, and use command-specific help when you are unsure about one command.

Agent Skills

Agent Skills are outcome-oriented playbooks for Codex, Claude Code, and other tools that read SKILL.md. You describe the research outcome in ordinary language; the agent follows the scoped workflow, uses the CLI or dedicated pipeline, reads the saved evidence, and returns a usable answer.

Use an Agent Skill when you want help completing a research task. Use the CLI when you want to run and tune commands yourself. Both routes save reproducible artifacts under runs/.

The four-step path

Choose by the answer you need

Pick one directory that matches your goal. Install just that directory first; you can add more later without changing your configuration.

Get the Skill pack

Clone the source once. When the skills are updated, return to this checkout and run git pull.

git clone https://github.com/zjunlp/SciAtlas.git
cd SciAtlas

Run every copy command below from the repository root. The example installs literature review; replace that final folder name with the Skill you picked above.

Install one selected Skill

Installing one Skill is the recommended start. It keeps your agent's menu focused and makes it obvious which workflow owns the task.

Codex

Windows PowerShell

# Example: install only sciatlas-literature-review
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse .\agent-skill\sciatlas-literature-review "$env:USERPROFILE\.codex\skills\"

macOS / Linux

# Example: install only sciatlas-literature-review
mkdir -p ~/.codex/skills
cp -R ./agent-skill/sciatlas-literature-review ~/.codex/skills/
Claude Code

Windows PowerShell

# Example: install only sciatlas-literature-review
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null
Copy-Item -Recurse .\agent-skill\sciatlas-literature-review "$env:USERPROFILE\.claude\skills\"

macOS / Linux

# Example: install only sciatlas-literature-review
mkdir -p ~/.claude/skills
cp -R ./agent-skill/sciatlas-literature-review ~/.claude/skills/
Optional: install every SciAtlas Skill

Replace the selected directory with sciatlas-* only if you want every workflow available in the same agent environment.

Codex

# Windows PowerShell
Copy-Item -Recurse .\agent-skill\sciatlas-* "$env:USERPROFILE\.codex\skills\"

# macOS / Linux
cp -R ./agent-skill/sciatlas-* ~/.codex/skills/

Claude Code

# Windows PowerShell
Copy-Item -Recurse .\agent-skill\sciatlas-* "$env:USERPROFILE\.claude\skills\"

# macOS / Linux
cp -R ./agent-skill/sciatlas-* ~/.claude/skills/

Start with a plain-language request

Open a new agent session after installation, then state the outcome you want. For example: “Create an evidence-backed literature-review outline for retrieval-augmented generation since 2020.” The Skill guides setup, runs its allowed retrieval or workflow, reads runs/<run_id>/ artifacts, and synthesizes the result.

The agent handles tool setup, registration guidance, environment configuration, execution, artifact reading, and synthesis. You provide only human-only values: email verification, your SciAtlas token, credentials that a selected workflow actually needs, and one necessary task clarification. Keep tokens and run artifacts outside agent-skill/.

When “flash” and “full” matter

Credentials, scoped to the goal

Start with the SciAtlas token. Ask for additional credentials only when the selected workflow needs them; do not collect every possible secret up front.

Advanced: verify each Skill's execution boundary

This reference shows the exact command or workflow each Skill is allowed to use. It is useful for maintainers and for debugging, not required for a first run.

CLI presets such as *-full expand saved JSON into commands. Agent Skills are SKILL.md playbooks that guide multi-step agent behavior. The *-full names are CLI preset names, not Agent Skill directories.

Quick Start

1. Install

Create a virtual environment, activate it in the shell you actually use, then install the local SciAtlas package.

Windows PowerShell 
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e .\sciatlas
macOS / Linux 
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ./sciatlas

If PowerShell blocks activation, run Set-ExecutionPolicy -Scope Process Bypass once in that terminal, then activate again.

1b. Prepare dedicated workflows

The package-only installation above is sufficient for core CLI retrieval. Literature review, idea evaluation, and idea generation require a full repository checkout plus workflow dependencies. The uv installer does this automatically; otherwise run:

git clone https://github.com/zjunlp/SciAtlas.git
cd SciAtlas
python -m pip install -e ./sciatlas
python -m pip install -r requirements-workflows.txt
python run_sciatlas.py literature-review -h

2. Configure your token

Register a personal token, then expose it to the CLI. The CLI sends it as Authorization and X-API-Key headers when it calls the hosted SciAtlas backend.

Open token registration

Windows PowerShell 
$env:SCIATLAS_API_BASE_URL = "http://sciatlas.openkg.cn"
$env:SCIATLAS_API_KEY = "your-personal-sciatlas-token"
macOS / Linux 
export SCIATLAS_API_BASE_URL="http://sciatlas.openkg.cn"
export SCIATLAS_API_KEY="your-personal-sciatlas-token"

These commands apply to the current shell session. For a persistent Windows variable, use setx and open a new PowerShell window afterward.

3. Check the setup

sciatlas health
sciatlas config
sciatlas search-papers -h

4. Run a first retrieval

Start with a small result set. Once the topic and anchors look right, increase --top-k or adjust ranking preferences.

sciatlas search-papers \
  --query "open world agent" \
  --domain "artificial intelligence" \
  --time-range 2020-2024 \
  --keyword "high:open world agent" \
  --top-k 3 \
  --top-keywords 0 \
  --max-titles 0 \
  --max-refs 0

After the command finishes, check the new folder under runs/. It keeps the request, response, metadata, and report so the result can be shared or reproduced.

Windows PowerShell users can use setx or $env:SCIATLAS_API_KEY="..." for the current session.

Input Styles

Recommended: expert parameters

Best for formal use. You state the topic, domain, time range, keywords, title anchors, and ranking preference explicitly.

Compatible: natural language

Best for quick exploration. Put your intent in --text; SciAtlas extracts a plan and can also read structured hints inside the text.

Anchor Levels

Anchors tell SciAtlas which signals should pull the graph closer to your real intent. Use high for must-match ideas, middle for helpful context, and low for weak hints.

Expert example

sciatlas --timeout 900 search-papers \
  --retrieval-mode hybrid \
  --query "open world agent" \
  --domain "artificial intelligence" \
  --time-range 2020-2024 \
  --keyword "high:open world agent" \
  --keyword "middle:embodied agent" \
  --title "middle:Voyager: An Open-Ended Embodied Agent with Large Language Models" \
  --reference "low:JARVIS-1: Open-World Multi-task Agents with Memory-Augmented Multimodal Language Models" \
  --top-k 5 \
  --top-keywords 0 \
  --max-titles 0 \
  --max-refs 0 \
  --bias-keyword high \
  --bias-related high \
  --bias-exploration low \
  --ranking-profile precision \
  --report-max-items 5

Natural-language example

sciatlas --timeout 900 search-papers \
  --retrieval-mode hybrid \
  --text "Find papers about open world agent in artificial intelligence after 2020. Return 3 papers.

Keywords[high]: open world agent" \
  --top-k 3 \
  --top-keywords 1 \
  --max-titles 0 \
  --max-refs 0

Parameter Guide

These parameter groups are reused by most SciAtlas commands. Command-specific parameters are listed in the command cards below.

Global options

Input options

Plan and anchor options

Retrieval options

Retrieval and Ranking Choices

Output options

Command Reference

Use the search box to find a workflow or parameter. Each card includes what the command does, the parameter groups it accepts, command-specific options, and a working example.

Command Map

Use this table when you know the task but are not sure which command to start from.

Common Examples