-
Notifications
You must be signed in to change notification settings - Fork 0
faq
pipx install cross-st # or: pip install cross-st
st-admin --setup # interactive wizard--setup walks you through:
- Checking Python version and Homebrew (macOS)
- Entering API keys for each provider you want to use
- Setting your default AI provider (
DEFAULT_AGENT) - Setting your editor and TTS voice (optional)
- Optionally joining the crossai.dev community
All settings are written to ~/.crossenv. Run st-admin --show at any time
to see the current configuration.
st-admin --discourse-setupThis runs the full Discourse onboarding independently: accepts the Terms of Service,
opens the crossai.dev signup page, provisions your account, and writes the required
keys to ~/.crossenv. You do not need to re-run --setup.
st-admin --discourseThis opens an interactive manager showing your current site, username, and default posting category. You can switch between:
- Your private category (created during onboarding — visible only to you)
-
Test (cleared daily) — a public sandbox on crossai.dev; all posts are
automatically deleted at 00:05 UTC every night. Safe for testing
st-post. - Any other category ID (enter manually)
The change takes effect immediately for the next st-post call.
First-run note: If
--discourse-setupcompleted butst-poststill fails, runst-admin --discourseonce. It will automatically migrate the flatDISCOURSE_*keys to theDISCOURSEJSON format thatst-postneeds.
Quick one-liner:
st-admin --set-default-ai gemini # or: xai anthropic openai perplexityOr run the full interactive menu:
st-adminand choose Default AI. The setting is written as DEFAULT_AGENT=gemini in
~/.crossenv. You can also edit ~/.crossenv directly in any text editor.
Available providers:
| Provider | Key variable | Free tier? |
|---|---|---|
gemini |
GEMINI_API_KEY |
✅ Yes — aistudio.google.com |
xai |
XAI_API_KEY |
Free credits on signup |
anthropic |
ANTHROPIC_API_KEY |
Paid only |
openai |
OPENAI_API_KEY |
Paid only |
perplexity |
PERPLEXITY_API_KEY |
Paid only |
Every time Cross calls an AI, the response is saved to ~/.cross_api_cache/ using
an MD5 key derived from the exact prompt and model. On the next run with the same
prompt and model, Cross returns the saved response instantly — no API call, no cost,
no wait.
Why this matters:
-
st-crossruns up to 25 AI calls for a single topic (5 providers × 5 fact-checks). Without the cache, re-running any step re-bills every one of those calls. - Iterating on
st-fixorst-prepoptions is free once the story is cached. - The cache is transparent — you never need to manage it to get the benefit.
To bypass the cache (force a fresh API call):
st-gen --no-cache my_topic.json
st-fact --no-cache my_topic.jsonTo disable caching globally, add to ~/.crossenv:
CROSS_NO_CACHE=1
st-admin --cache-infoPrints the cache path, number of files, and total size.
st-admin --cache-clear # delete all cached responses
st-admin --cache-cull 30 # delete entries older than 30 daysThe cache at ~/.cross_api_cache/ is safe to delete at any time — Cross will
simply re-call the API on the next run. Your story files (.json containers) are
not affected.
Short answer: yes, completely safe.
st-admin --upgrade upgrades the Cross software only. It does not touch any of
your data or configuration:
| Location | Contains | Touched by --upgrade? |
|---|---|---|
~/.crossenv |
API keys, DEFAULT_AGENT, preferences | ❌ Never |
~/.cross_api_cache/ |
Cached AI responses | ❌ Never |
~/.cross_templates/ |
Prompt templates | ❌ Never |
~/cross-stones/ |
Benchmark domain prompts | ❌ Never |
Your .json story files |
Stories, fact-checks | ❌ Never |
The upgrade only replaces the Python package (cross-st and cross-ai-core).
After upgrading, all your API keys, stories, benchmarks, and cached responses are
exactly where you left them.
What --upgrade does:
- Detects whether you installed with
pipxorpipand uses the right command - Skips the PyPI step if you're on an editable (developer) install
- On macOS, also runs
brew upgradefor tracked Homebrew tools (e.g.piper-tts) - Prints the version before and after so you can confirm the upgrade succeeded
If anything looks wrong after an upgrade, your config is in ~/.crossenv and
is always readable/editable in a plain text editor.
| Path | Contents |
|---|---|
~/.crossenv |
API keys, DEFAULT_AGENT, CROSS_STONES_DIR, and other preferences |
~/.cross_api_cache/ |
MD5-keyed AI response cache (safe to delete at any time) |
~/.cross_templates/ |
Prompt templates used by st-new
|
~/cross-stones/ |
Benchmark domain .prompt files (default; override with CROSS_STONES_DIR) |
Move the directory, then set CROSS_STONES_DIR in ~/.crossenv:
mv ~/cross-stones ~/research/my-benchmarksOpen ~/.crossenv in any editor and add:
CROSS_STONES_DIR=~/research/my-benchmarks
st-stones will find the new location automatically. Run st-admin --show to
confirm the active path is correct.
Google Gemini is the only provider with a genuinely free API tier — no credit card required, just a Google account. Get a key at https://aistudio.google.com/app/apikey.
Run st-admin --setup to enter your keys and set a default provider.
Step 1 — Remove the package
pipx uninstall cross-st # if installed with pipx (recommended)
pip uninstall cross-st # if installed with pipStep 2 — Remove user data
Cross stores data in four locations under your home directory. Remove whichever you want to clean up:
rm -f ~/.crossenv # API keys, DEFAULT_AGENT, all preferences
rm -rf ~/.cross_api_cache/ # cached AI responses (safe to delete any time)
rm -rf ~/.cross_templates/ # prompt templates seeded by st-admin
rm -rf ~/cross-stones/ # benchmark domain prompts (if you ran st-stones)If you moved your benchmark directory with CROSS_STONES_DIR, remove that path
instead of ~/cross-stones/.
One-liner to remove everything at once:
rm -f ~/.crossenv && rm -rf ~/.cross_api_cache/ ~/.cross_templates/ ~/cross-stones/Your
.jsonstory files are not touched — they live wherever you created them (your working directory) and are never stored in the home-directory paths above. Keep or delete them as you choose.