From cecad5e009754de6b4f80bfc60a3c49f45c0a3fa Mon Sep 17 00:00:00 2001 From: Gold Okpa Date: Fri, 21 Aug 2026 08:41:35 +0100 Subject: [PATCH] docs(cli): add production onboarding guide --- docs-site/docs.json | 5 ++ docs-site/guides/cli.mdx | 116 ++++++++++++++++++++++++++++++++ docs-site/guides/production.mdx | 7 ++ docs-site/quickstart.mdx | 3 + 4 files changed, 131 insertions(+) create mode 100644 docs-site/guides/cli.mdx 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.