CLI

skillhook cloud login, overview, tools and every tool by name.

skillhook cloud

skillhook 0.7.0 and newer run the whole catalogue from the terminal with an organisation API key: everything the dashboard shows and does, as skillhook cloud subcommands. The commands and their parameters are built from the cloud's own listing when you run them, so a tool the cloud adds works without a new skillhook. The machine running the CLI does not need to be paired; the key is enough.

npm install -g @meterapp/skillhook
skillhook cloud login --url https://skillhook.dev     # asks for the key without echoing it; --key - reads it from stdin
skillhook cloud status                          # the link, and whether a key is kept and for which cloud
skillhook cloud logout                          # forgets the key

Login checks the key against the cloud named by --url (else the one logged in to before, else the machine's; when those two differ it asks which) and keeps it in ~/.skillhook/.env as SKILLHOOK_CLOUD_API_KEY with SKILLHOOK_CLOUD_API_URL. It never touches the machine's pairing link, and the machine's token is never used for these commands. The same two variables in the environment work for CI; see API keys and scopes.

Fixed views

skillhook cloud overview                       # what needs a person: waiting agents, open alerts, failing checks, failed jobs, rejected webhooks, the day's numbers, next steps
skillhook cloud machines                       # status, mode, link, runners, version, last seen
skillhook cloud jobs --waiting                 # agents waiting for an answer
skillhook cloud jobs --machine mac-mini --status failed --limit 50
skillhook cloud job job_01j9x                  # one job: status, outcome, failure, question, timeline
skillhook cloud tools                          # every tool the key has, and which a wider key would add
skillhook cloud tools answer_job               # one tool: its parameters and their types

Every command prints a table or indented text, and the API's JSON as it came with --json. Text from the cloud, machines and senders reaches the terminal without control characters or bidirectional overrides, error messages included.

Running any tool by name

skillhook cloud <tool> [args] [--param value]… runs any tool of the catalogue. The words after the tool's name are read with the tool's schema; before it, only skillhook's own options.

Required parameters go as positional arguments, in the order the schema lists them; any parameter can be given as a flag instead.
--param value or --param=value. Numbers are checked against the schema.
Booleans are switches: --waiting, --force, --skip_filters.
JSON parameters (a payload, headers, a command's arguments) take a JSON literal, @file, or - for stdin.
--param-file PATH reads a long text parameter from a file: --content-file SKILL.md, --skill_md-file draft.md.
--input gives the whole input as one JSON object (a literal, @file or -).
--json, --help, --version and --dir are skillhook's own options wherever they stand and are never a parameter's value: --answer=--help sends that text, and --help never runs a tool.

skillhook cloud answer_job job_01j9x "yes" --option yes
skillhook cloud get_stats --days 30 --json
skillhook cloud run_skill mac-mini triage --payload @event.json --wait_seconds 120
skillhook cloud save_skill mac-mini triage --content-file ./skills/triage/SKILL.md
skillhook cloud replay_delivery dlv_8f2 --force
skillhook cloud get_job_artifact job_01j9x stderr
skillhook cloud send_command mac-mini health.get --args '{"deep": true}'
skillhook cloud list_jobs --input '{"status": "failed", "failure": "auth", "limit": 100}'

A catalogue entry this skillhook cannot read (a malformed schema included) is skipped; a newer catalogue shape asks for an update.

A skill's secret, sealed end to end

skillhook cloud secret <machine> <skill|NAME> [--force] has the machine generate a skill's webhook secret and shows it in this terminal, once. The CLI makes a key pair for that one request; the machine seals the secret to it; the cloud keeps the sealed value for at most two minutes and hands it to the key that asked, once; only this terminal can open it. Only a skill's secret: never the machine's admin token or a runner's key. Without --force a secret the machine already has is kept. This is why it is not a catalogue tool: a model behind the hosted MCP server could not open it.

skillhook cloud secret mac-mini sentry-triage            # the skill's secret, generated on mac-mini, shown here once
skillhook cloud secret mac-mini sentry-triage --force    # replace the one it has

What each fixed view asks the cloud

Everything the CLI does is a request any other client could make with the same key; nothing is special to it.

Command	Request
skillhook cloud login	GET /api/v1/me: checks the key and its organisation, then keeps it
skillhook cloud status	Nothing: reads the machine's link and whether a key is kept, and for which cloud
skillhook cloud overview	POST /api/v1/tools/describe_cloud
skillhook cloud machines	GET /api/v1/machines
skillhook cloud jobs [--waiting …]	GET /api/v1/jobs?waiting=1&…
skillhook cloud job <id>	GET /api/v1/jobs/{id}
skillhook cloud tools [tool]	GET /api/v1/tools: the catalogue, with what this key may call
skillhook cloud <tool> …	POST /api/v1/tools/{tool} with the input built from the arguments
skillhook cloud secret <machine> <skill>	POST /api/v1/machines/{machine}/secrets, then POST /api/v1/commands/{id}/claim for the sealed value
skillhook cloud report "<title>"	POST /api/agent/issues with the machine's own token (no API key needed)

Problem reports from a paired machine

skillhook cloud report "<title>" files a problem with the Skillhook team from a paired machine with the diagnostics it already has (versions, link state, runner readiness, failing checks), scrubbed of every .env value and never with payloads or logs; --dry-run shows the JSON. With a key, skillhook cloud report_issue does the same through the catalogue, and list_issues and get_issue follow it up.