diff --git a/docs-site/docs.json b/docs-site/docs.json
index 29b2b54f..abc75ad2 100644
--- a/docs-site/docs.json
+++ b/docs-site/docs.json
@@ -23,6 +23,7 @@
"pages": [
"introduction",
"quickstart",
+ "guides/cli",
"concepts"
]
},
@@ -73,6 +74,10 @@
{
"label": "SDK on PyPI",
"href": "https://pypi.org/project/identark/"
+ },
+ {
+ "label": "CLI on PyPI",
+ "href": "https://pypi.org/project/identark-cli/"
}
],
"primary": {
diff --git a/docs-site/guides/cli.mdx b/docs-site/guides/cli.mdx
new file mode 100644
index 00000000..0386844b
--- /dev/null
+++ b/docs-site/guides/cli.mdx
@@ -0,0 +1,116 @@
+---
+title: "IdentArk CLI"
+description: "Register agents, manage capability references, and approve high-risk work from your terminal."
+---
+
+# Govern agents from your terminal
+
+The IdentArk CLI is the operational companion to the control plane. Use it to
+register agents, keep credential references out of your repository, and review
+human-in-the-loop approvals without giving a production agent raw credentials.
+
+## Install
+
+```bash
+pip install identark-cli
+identark --version
+```
+
+The CLI requires Python 3.11 or later. Pin the version in CI or a deployment
+image when you need a repeatable release.
+
+## Sign in
+
+
+
+ ```bash
+ identark auth login
+ identark auth status
+ ```
+
+ The CLI starts a device-authorisation flow, then stores the resulting
+ session in your operating system keychain. It never prints the raw token.
+
+
+
+ ```bash
+ identark auth login --no-browser
+ ```
+
+ For automation, provide a narrowly scoped key at runtime instead of
+ persisting one on disk:
+
+ ```bash
+ export IDENTARK_API_KEY='csk_…'
+ identark agent list
+ ```
+
+
+
+## Set up an agent project
+
+```bash
+identark init
+identark credential add OPENAI_API_KEY --ref vault://prod/openai
+identark credential scan --strict
+```
+
+`identark init` creates `.identark/config.toml`. That file holds project
+configuration and references such as `vault://prod/openai` or `env://OPENAI_API_KEY`—never
+the credential value itself. Commit the configuration if it is useful to your
+team; do not commit a `.env` file containing real secrets.
+
+Register an agent with the control plane when it is ready to be governed:
+
+```bash
+identark agent register \
+ --name support-agent \
+ --provider anthropic \
+ --model claude-sonnet-4-5 \
+ --credential-ref vault://prod/anthropic
+
+identark agent list
+```
+
+## Production boundary
+
+
+`identark credential inject`, `identark agent run`, and `identark agent dev`
+are local-development helpers. They resolve a scalar secret into a child
+process environment, so that process can read it. They are not a production
+secret-isolation boundary.
+
+
+For a production agent, use the SDK's `ControlPlaneGateway` or an IdentArk
+managed connector. The agent receives a scoped capability and the control plane
+enforces policy, records activity, and applies any required approval. See
+[Going to production](/guides/production) for the runtime pattern.
+
+```text
+CI or operator terminal → IdentArk CLI
+Production agent → ControlPlaneGateway / managed MCP tools
+Sensitive operations → capability checks + human approval when required
+```
+
+## Review high-risk work
+
+```bash
+identark approvals list
+identark approvals inspect
+identark approvals approve
+identark approvals reject --reason "Unexpected production change"
+```
+
+Approvals require an explicit command. A pending approval expires to **deny**;
+the CLI has no auto-approve mode.
+
+## Next
+
+
+
+ Run agents with a scoped session, not provider credentials.
+
+
+ Put policy and human review in front of high-risk tools.
+
+
diff --git a/docs-site/guides/production.mdx b/docs-site/guides/production.mdx
index 8115209d..ef4edf76 100644
--- a/docs-site/guides/production.mdx
+++ b/docs-site/guides/production.mdx
@@ -7,6 +7,13 @@ The production pattern has one rule: **the provider key never reaches the agent
An admin stores it in the vault; the agent runs with only a scoped `csk_` key and a
session id.
+
+Use the [IdentArk CLI](/guides/cli) for operator and CI workflows such as agent
+registration, capability references, and approval review. Do not use
+`credential inject` to run a production agent: it intentionally exposes a scalar
+secret to its local child process.
+
+
Done once, with an admin key, on your control side.
diff --git a/docs-site/quickstart.mdx b/docs-site/quickstart.mdx
index 490dfd44..3a94031b 100644
--- a/docs-site/quickstart.mdx
+++ b/docs-site/quickstart.mdx
@@ -89,6 +89,9 @@ your first cost-accounted LLM call. Total time: about ten minutes.
## Next
+
+ Register agents, manage capability references, and approve high-risk work from your terminal.
+
Store the secret once, hand the agent a session, never the key.