SDK Reference

CLI Reference

The niitaka command manages policies as code — validate a file locally, push it to the backend, pull the live state back down, or review who changed what. Installed alongside the SDK, no separate package.

Install

bash

pip install niitaka-sdk
niitaka --help

You may not need push at all

As of SDK v0.1.20, niitaka.configure(policy_file=...) auto-syncs the file to the backend on startup (fire-and-forget) whenever an api_key is set. push is mainly useful for a one-off sync outside of running the agent itself — e.g. from CI, or before the agent's first run.

Commands

niitaka validate <file>

Parse and validate a policy YAML/JSON file without contacting the backend. Catches shape errors before you push.

bash

niitaka validate policies.yaml
# ✓ Valid policy file — 4 policies across 1 agent(s):
#    my-agent: 4 rule(s)

niitaka push <file> [--dry-run] [--url URL] [--key KEY]

Validate, then upload policies from a file to the backend DB, replacing the matching agents' existing policies. --dry-run validates and shows the target agents without making changes.

bash

niitaka push policies.yaml
niitaka push policies.yaml --dry-run          # show what would change, make no changes
niitaka push policies.yaml --url https://api.niitaka.ai --key nk-...

niitaka pull [--agent AGENT_ID] [-o FILE]

Download the current DB policies for one agent or all agents, printed as YAML (or written to a file with -o).

bash

niitaka pull                          # all agents, prints YAML to stdout
niitaka pull --agent my-agent         # filter to one agent
niitaka pull -o policies.yaml         # write to a file instead of stdout

niitaka history [--agent AGENT_ID] [--limit N]

Show the policy audit log — who changed what, when, and from where (file push vs. dashboard edit). Defaults to the 50 most recent entries.

bash

niitaka history
niitaka history --agent my-agent --limit 20

# Timestamp             Agent                 Action    Type          Src
# ──────────────────────────────────────────────────────────────────────
# 2026-10-05T14:32:01    my-agent              created   cost_limit    file
# 2026-10-04T09:11:47    my-agent              updated   step_limit    dashboard

Backend URL & API key

push, pull, and history talk to the backend, so they need a URL and key. Both can come from flags or environment variables — flags win:

--url / $NIITAKA_BACKEND_URL — defaults to http://localhost:8000
--key / $NIITAKA_API_KEY — your org's API key

Environments

REST API & Scoped Tokens

Was this page helpful?

Need help? Contact Support Questions? Contact Sales LLM? Read llms.txt