Puras CLI Reference

The puras CLI deploys skillpacks and runs jobs from your terminal or CI. It ships in the same package as the SDK — to call deployed skills from application code instead, see the SDK Client Reference.

Install

bash

pip install puras

Then authenticate once with a workspace API key (puras_live_…, minted in the dashboard):

bash

puras login            # prompts for the key, or opens the dashboard
puras whoami           # confirm the active workspace + balance

Credentials are stored in ~/.puras/config.json. In CI, skip login and set PURAS_API_KEY in the environment instead. Most commands resolve the target skillpack from a puras.yaml in the working directory — the pack manifest holding the remote binding plus the pack page's title/description/marketing (see the skill.yaml reference), written by puras init; override with --skillpack.

Commands

`puras login`

Store + verify a workspace API key.

Argument	Kind	Description
`--key` KEY	optional	API key (else you'll be prompted / browser opens)
`--api-base` API_BASE	optional	override API base URL

`puras logout`

Remove stored credentials.

`puras whoami`

Show the active workspace + balance.

`puras init`

Scaffold a skill and write puras.yaml.

Argument	Kind	Description
`--name` NAME	optional
`--slug` SLUG	optional
`--description` DESCRIPTION	optional
`--template` TEMPLATE	optional	starter files: a minimal blank skill (default) or the full hello-world example (github.com/PurasAI/hello-world)
`--no-scaffold`	flag	don't write any starter files

`puras skillpacks`

List your skills.

`puras skills`

`puras deploy`

Bundle a skill dir and push a deployment.

Argument	Kind	Description
`path`	positional	skill dir (default: .)
`--app`, `--skillpack` SKILLPACK	optional	skill id or slug to deploy to (default: puras.yaml, the skill's name, or the dir name; created on first deploy)
`--no-activate`	flag	upload without activating
`--notes` NOTES	optional

`puras deployments`

List deployments for the skill.

Argument	Kind	Description
`--app`, `--skillpack` SKILLPACK	optional

`puras activate`

Activate a deployment by version or id.

Argument	Kind	Description
`ref`	positional	version number (e.g. 3) or deployment id
`--app`, `--skillpack` SKILLPACK	optional

`puras run`

Submit a job and wait for the result.

Argument	Kind	Description
`skill`	positional	skill name, or a path copied from the skill's page (optional with --local when the bundle has one skill)
`-p`, `--prompt` PROMPT	optional	run a one-off agent from this inline prompt — NO skill, NO deploy needed. Use `-` to read stdin or `@file` to read a file.
`-i`, `--input` KEY=VALUE	optional	repeatable
`--json` JSON	optional	inputs as a JSON object
`--async`	flag	don't wait
`--timeout` TIMEOUT	optional	wait seconds (default 60)
`--app`, `--skillpack` SKILLPACK	optional	default skill id or slug for a bare skill name
`--version` VERSION	optional	pin to a deployment version (default: active)
`--local`	flag	run a local skill bundle OFFLINE (no platform) on your own LLM key
`--dir` DIR	optional	bundle dir for --local (default: current directory)
`--api-key` API_KEY	optional	LLM key for --local (default: $ANTHROPIC_API_KEY)
`--model` MODEL	optional	override the skill's model slug for --local

`puras serve`

Serve a local API for a bundle (the hosted job API, offline).

Argument	Kind	Description
`--dir` DIR	optional	bundle dir to serve (default: current directory)
`--host` HOST	optional	bind host (default 127.0.0.1)
`--port` PORT	optional	bind port (default 8787)
`--api-key` API_KEY	optional	LLM key used to run jobs (default: $ANTHROPIC_API_KEY)
`--model` MODEL	optional	override each skill's model slug
`--require-key` TOKEN	optional	emulate API-key auth: require `Authorization: Bearer TOKEN` on /v1/* requests

`puras logs`

Stream a job's events until it finishes.

Argument	Kind	Description
`job_id`	positional
`--timeout` TIMEOUT	optional
`--interval` INTERVAL	optional

`puras spans`

Show a job's trace spans (run/step/model/tool latency).

Argument	Kind	Description
`job_id`	positional
`--json`	flag	print the raw spans as JSON

`puras feedback`

Rate a job's result (👍/👎 + optional comment).

Argument	Kind	Description
`job_id`	positional
`--up`	flag	thumbs up (good result)
`--down`	flag	thumbs down (bad result)
`--comment`, `-c` COMMENT	optional	free-form note on why
`--end-user` ID	optional	opaque id of the end user this feedback is for

`puras replay`

Re-run a past job's inputs (reproduce it locally).

Argument	Kind	Description
`job_id`	positional	the job to replay
`--version` VERSION	optional	pin a deployment version (default: active / local)

`puras eval`

Run a skill's eval suite (dataset + graders).

Argument	Kind	Description
`skill`	positional	skill name (resolved from --app / puras.yaml; optional with --local when the bundle has one skill)
`--app`, `--skillpack` SKILLPACK	optional	skill id (default: puras.yaml binding)
`--version` VERSION	optional	pin to a deployment version (default: active)
`--repeat` REPEAT	optional	run each case N times for variance (default 1)
`--threshold` THRESHOLD	optional	CI gate: fail if pass-rate %% is below this
`--case` CASE	optional	run only this case id (repeatable)
`--json`	flag	print the full report as JSON
`--async`	flag	kick off and return; don't wait
`--timeout` TIMEOUT	optional	max seconds to wait (default 900)
`--interval` INTERVAL	optional	poll interval seconds (default 3)
`--local`	flag	run the eval suite OFFLINE on a local bundle, on your own LLM key
`--dir` DIR	optional	bundle dir for --local (default: current directory)
`--api-key` API_KEY	optional	LLM key for --local (default: $ANTHROPIC_API_KEY)
`--model` MODEL	optional	override the skill's model slug for --local

`puras eval-report`

Show an eval suite report by id.

Argument	Kind	Description
`suite_id`	positional
`--json`	flag	print the full report as JSON

`puras eval-diff`

A/B two eval suites (version vs version).

Argument	Kind	Description
`skill`	positional	the skill both suites evaluated
`--app`, `--skillpack` SKILLPACK	optional	skill id (default: puras.yaml binding)
`--base` BASE	optional	baseline: a version number or a suite id
`--head` HEAD	optional	candidate: a version number or a suite id
`--json`	flag	print the full diff as JSON

`puras hindsight`

Analyze a skill's recent runs for recurring inefficiencies.

Argument	Kind	Description
`skill`	positional	skill name to analyze
`--app`, `--skillpack` SKILLPACK	optional	skill id (default: puras.yaml binding)
`--wait`	flag	wait for the report and print it
`--timeout` TIMEOUT	optional	max seconds to wait with --wait (default 600)
`--interval` INTERVAL	optional	poll interval seconds (default 5)
`--json`	flag	print the run/report as JSON

`puras hindsight-list`

List/search past Hindsight retrospectives.

Argument	Kind	Description
`--app`, `--skillpack` SKILLPACK	optional	skill id (default: puras.yaml binding)
`--skill` SKILL	optional	filter to one skill
`--json`	flag	print as JSON

`puras hindsight-show`

Read one Hindsight report by run id.

Argument	Kind	Description
`run_id`	positional
`--json`	flag	print the full report as JSON

`puras secrets`

Manage your skill's secrets.

`puras secrets set`

Set a secret (NAME=VALUE or prompt).

Argument	Kind	Description
`NAME[=VALUE]`	positional
`--app`, `--skillpack` SKILLPACK	optional

`puras secrets ls`

List secret names.

Argument	Kind	Description
`--app`, `--skillpack` SKILLPACK	optional

`puras secrets rm`

Delete a secret.

Argument	Kind	Description
`name`	positional
`--app`, `--skillpack` SKILLPACK	optional

`puras pull`

Download the active bundle.

Argument	Kind	Description
`--app`, `--skillpack` SKILLPACK	optional
`--out` OUT	optional	output dir (default: .)