FAQ

FAQ

Quick answers to common questions. For depth, each answer links to the canonical docs in the repository.

Is this official? Is it safe to use?

No — it's an unofficial, independent open-source client, not affiliated with or endorsed by Capital.com. It talks to Capital.com's public Open API using your own API key. It defaults to the demo environment and keeps trading disabled until you explicitly opt in, so you can explore risk-free. CFD trading carries a high risk of losing money; nothing here is financial advice. See the security & safety model.

How do I install it?

pipx install capitalcom-cli            # recommended
uv tool install capitalcom-cli         # or with uv
brew install SimonTarara62/tap/capctl  # macOS/Linux, Homebrew
pip install capitalcom-cli             # into an active virtualenv

More options: installation channels.

Where do I get API credentials?

In the Capital.com app: Settings → API integrations → generate an API key. You'll set three values in a .env file: CAP_API_KEY, CAP_IDENTIFIER (your login email), and CAP_API_PASSWORD. Full walkthrough: getting started.

Login fails with "authentication failed" (exit 5). Why?

The most common cause: CAP_API_PASSWORD must be the custom password you set when generating the API key — not your Capital.com account password. Also check the key isn't expired/revoked and that a demo key is used with demo (and a live key with --live). See troubleshooting.

How do I actually place a trade?

Trading is off by default. Enable it deliberately in .env: CAP_ALLOW_TRADING=true and list the markets you allow in CAP_ALLOWED_EPICS (e.g. GOLD,BTCUSD, or ALL). Every order is two-phase — trade preview-* first, then trade execute-* with --yes. This friction is intentional. See use cases.

Demo vs. live?

capctl uses the demo environment by default (virtual money). Live requires an explicit opt-in (a live API key and the --live flag). Keep everything on demo until you know exactly what you're doing.

Does it store or leak my API keys?

No. Your API key/password are never written to disk by capctl. It persists only trade previews, the daily-order counter, and (by default) a short-lived session token in ~/.config/capital-cli/state.json (mode 0600). Deleting that file is safe. See where is my state stored.

I keep getting HTTP 429 on login. What's wrong?

Capital.com limits how often you can create sessions. capctl caches the short-lived session token by default (CAP_PERSIST_SESSION=true) so back-to-back commands reuse one login — keep it enabled. Scripts firing many commands should pause ~1s between them. Details: troubleshooting.

What do the exit codes mean?

Each failure class has its own exit code (2 = bad input, 3 = config, 4 = safety policy, 5 = auth, 6 = local rate limit, 7 = broker/upstream, 8 = preview). Full table: troubleshooting. Every command also supports --json for machine-readable output.

What's the difference between the CLI and the SDK?

capctl is the terminal/scripting surface. The same tested broker engine is also importable as an async Python library (from capital_cli.sdk import CapitalComApp) with a stable 0.x API — useful for dashboards, bots, or your own integrations. See use as a library.

Can I use it with automation or AI agents?

Yes. Every command emits JSON with --json and returns distinct exit codes, so it drops cleanly into cron jobs, CI, and scripts. For programmatic use, prefer the SDK over shelling out. See scripting & automation.

How do I report a bug or contribute?

Open an issue with the failing command, its output (it never contains your secrets), and your OS/Python version. First-time contributors: see CONTRIBUTING and the good first issue label.